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ABOUT THIS CHAPTER 


The Window Manager is the part of the Toolbox that allows you to create, 
manipulate, and dispose of windows. This chapter describes the Window Manager in 
detail, including the enhancements to the Window Manager provided for the 
Macintosh Plus, the Macintosh SE, and the Macintosh II. A new set of Window 
Manager routines for the Macintosh II supports the use of multiple screen 
desktops and color windows. New data structures and a new resource type, ‘wctb', 
have been introduced to store color window information. All handling of color 
windows and multiple screens is transparent to applications that aren't using 
the new features. 


To make use of the information in this chapter, you should be familiar with 


e the drawing environment described in the Color QuickDraw chapter 
« the use of resources in an application program, described in the 
Resource Manager chapter 


You should already be familiar with: 


¢ The basic concepts and structures behind QuickDraw, particularly 
points, rectangles, regions, grafPorts, and pictures. You don't 
have to know the QuickDraw routines in order to use the Window 
Manager, though you'll be using QuickDraw to draw inside a window. 
« The Toolbox Event Manager. 
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ABOUT THE WINDOW MANAGER 


The Window Manager is a tool for dealing with windows on the Macintosh screen. 
The screen represents a working surface or desktop; graphic objects appear on 
the desktop and can be manipulated with the mouse. A window is an object on the 
desktop that presents information, such as a document or a message. Windows can 
be any size or shape, and there can be one or many of them, depending on the 
application. 


Some standard types of windows are predefined. One of these is the document 
window, as illustrated in Figure 1. Every document window has a 20-pixel-high 
title bar containing a title that's centered and in the system font and system 
font size. In addition, a particular document window may or may not have a close 
box or a size box; you'll learn in this chapter how to implement them. There may 
also be scroll bars along the bottom and/or right edge of a document window. 
Scroll bars are controls, and are supported by the Control Manager. 
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Figure 1—-An Active Document Window 
Figure 1-An Active Document Window 


Your application can easily create standard types of windows such as document 
windows, and can also define its own types of windows. Some windows may be 
created indirectly for you when you use other parts of the Toolbox; an example 
is the window the Dialog Manager creates to display an alert box. Windows 
created either directly or indirectly by an application are collectively called 
application windows. There's also a class of windows called system windows; 
these are the windows in which desk accessories are displayed. 


The document window shown in Figure 1 is the active (frontmost) window, the one 
that will be acted on when the user types, gives commands, or whatever is 
appropriate to the application being used. Its title bar is 
highlighted—displayed in a distinctive visual way—so that the window will stand 
out from other, inactive windows that may be on the screen. Since a close box, 
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Size box, and scroll bars will have an effect only in an active window, none of 
them appear in an inactive window (see Figure 2). 
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Figure 2-—Overlapping Document Windows 


Figure 2—Overlapping Document Windows 


Note: If a document window has neither a size box nor scroll bars, 
the Lines delimiting those areas aren't drawn, as in the Memo 
window in Figure 2. 


An important function of the Window Manager is to keep track of overlapping 
windows. You can draw in any window without running over onto windows in front 
of it. You can move windows to different places on the screen, change their 
plane (their front-to-back ordering), or change their size, all without concern 
for how the various windows overlap. The Window Manager keeps track of any newly 
exposed areas and provides a convenient mechanism for you to ensure that they're 
properly redrawn. 


Finally, you can easily set up your application so that mouse actions cause 
these standard responses inside a document window, or similar responses inside 
other windows: 


e Clicking anywhere in an inactive window makes it the active window 
by bringing it to the front and highlighting its title bar. 

e Clicking inside the close box of the active window closes the window. 
Depending on the application, this may mean that the window disappears 
altogether, or a representation of the window (such as an icon) may be 
left on the desktop. 

« Dragging anywhere inside the title bar of a window (except in the 
close box, if any) pulls an outline of the window across the screen, 
and releasing the mouse button moves the window to the new location. 
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If the window isn't the active window, it becomes the active window 

unless the Command key was also held down. A window can never be 

moved completely off the screen; by convention, it can't be moved such 

that the visible area of the title bar is less than four pixels square. 
« Dragging inside the size box of the active window changes the size of 

the window. 


For the Macintosh Plus, the Macintosh SE, and the Macintosh II, the following 
Window Manager routines were changed to support hierarchical menus: 


¢ The InitWindow routine now calls the Menu Manager to calculate menu 
bar height, and to draw the empty menu bar. The FindWindow routine 
also makes a call to the Menu Manager when testing to see if a point 
on the screen has been selected. 


For the Macintosh II, the Window Manager has been enhanced to support multiple 
screen desktops and color windows: 


e Color windows can now be created within an application program. 

¢ Because window content regions may be colored on the Macintosh II, 
each window's area is now erased separately. Formerly, the Window 
Manager collected the update region of multiple windows into a single 
region, then erased this single region to white. 

« The standard desktop pattern may be a binary deskPattern or a color 
deskCPattern. If the color desktop pattern is enabled, InitWindows 
loads the default desktop pixel pattern as well as the standard binary 
pattern. 

¢ Windows may be dragged from one screen to another on a system 
configured with multiple screens. Changes to the DragGrayRgn routine 
allow the object being dragged to be positioned anywhere on the 
multiscreen desktop. The GetGrayRgn routine provides a handle to the 
global variable GrayRgn, which contains information about the current 
desktop. 

e The MoveWindow, GrowWindow, and ZoomWindow routines have been modified 
to ensure that windows will perform properly in a multiscreen environment. 
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WINDOWS AND GRAFPORTS 


It's easy for applications to use windows: To the application, a window is a 
grafPort that it can draw into like any other with QuickDraw routines. When you 
create a window, you specify a rectangle that becomes the portRect of the 
grafPort in which the window contents will be drawn. The bit map for this 
grafPort, its pen pattern, and other characteristics are the same as the default 
values set by QuickDraw, except for the character font, which is set to the 
application font. These characteristics will apply whenever the application 
draws in the window, and they can easily be changed with QuickDraw routines 
(SetPort to make the grafPort the current port, and other routines as 
appropriate). 


There is, however, more to a window than just the grafPort that the application 
draws in. In a standard document window, for example, the title bar and outline 
of the window are drawn by the Window Manager, not by the application. The part 
of a window that the Window Manager draws is called the window frame, since it 
usually surrounds the rest of the window. For drawing window frames, the Window 
Manager creates a grafPort that has the entire screen as its portRect; this 
grafPort is called the Window Manager port. 
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WINDOW REGIONS 


Every window has the following two regions: 


the content region: the area that your application draws in 
e the structure region: the entire window; its complete "structure" 
(the content region plus the window frame) 


The content region is bounded by the rectangle you specify when you create the 
window (that is, the portRect of the window's grafPort); for a document window, 
it's the entire portRect. This is where your application presents information 
and where the size box and scroll bars of a document window are located. 


A window may also have any of the regions listed below. Clicking or dragging in 
one of these regions causes the indicated action. 


¢ A go-away region within the window frame. Clicking in this region of 
the active window closes the window. 

e A drag region within the window frame. Dragging in this region pulls 
an outline of the window across the screen, moves the window to a new 
location, and makes it the active window (if it isn't already) unless 
the Command key was held down. 

« A grow region, usually within the content region. Dragging in this 
region of the active window changes the size of the window. In a 
document window, the grow region is in the content region, but in 
windows of your own design it may be in either the content region 
or the window frame. 


Clicking in any region of an inactive window simply makes it the active window. 
Note: The results of clicking and dragging that are discussed here don't 
happen automatically; you have to make the right Window Manager 
calls to cause them to happen. 


Figure 3 illustrates the various regions of a standard document window and its 
window frame. 
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Figure 3-Document Window Regions and Frame 
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Figure 3—Document Window Regions and Frame 


An example of a window that has no drag region is the window that displays an 
alert box. On the other hand, you could design a window whose drag region is the 
entire structure region and whose content region is empty; such a window might 
present a fixed picture rather than information that's to be manipulated. 


Another important window region is the update region. Unlike the regions 
described above, the update region is dynamic rather than fixed: The Window 
Manager keeps track of all areas of the content region that have to be redrawn 
and accumulates them into the update region. For example, if you bring to the 
front a window that was overlapped by another window, the Window Manager adds 
the formerly overlapped (now exposed) area of the front window's content region 
to its update region. You'll also accumulate areas into the update region 
yourself; the Window Manager provides update region maintenance routines for 
this purpose. 
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WINDOWS AND RESOURCES 


The general appearance and behavior of a window is determined by a routine 
called its window definition function, which is stored as a resource ina 
resource file. The window definition function performs all actions that differ 
from one window type to another, such as drawing the window frame. The Window 
Manager calls the window definition function whenever it needs to perform one of 
these type-dependent actions (passing it a message that tells which action to 
perform). 


The system resource file includes window definition functions for the standard 
document window and other standard types of windows. If you want to define your 
own, nonstandard window types, you'll have to write window definition functions 
for them, as described later in the section "Defining Your Own Windows". 


When you create a window, you specify its type with a window definition ID, 
which tells the Window Manager the resource ID of the definition function for 
that type of window. You can use one of the following constants as a window 
definition ID to refer to a standard type of window (see Figure 4): 


CONST documentProc = 0; {standard document window} 
dBoxProc = 1; {alert box or modal dialog box} 
plainDBox = 2; {plain box} 
altDBoxProc = 3; {plain box with shadow} 
noGrowDocProc = 4; {document window without size box} 
rDocProc = 16; {rounded-corner window} 


dB Proc plainDBox ahDBox Foc 


Figure 4-S3tandarn Types of Windows 
Figure 4—-Standard Types of Windows 
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DocumentProc represents a standard document window that may or may not contain a 
size box; noGrowDocProc is exactly the same except that the window must not 
contain a size box. If you're working with a number of document windows that 
need to be treated similarly, but some will have size boxes and some won't, you 
can use documentProc for all of them. If none of the windows will have size 
boxes, however, it's more convenient to use noGrowDocProc. 


The dBoxProc type of window resembles an alert box or a "modal" dialog box (the 
kind that requires the user to respond before doing any other work on the 
desktop). It's a rectangular window with no go-away region, drag region, or grow 
region and with a two-pixel-thick border two pixels in from the edge. It has no 
special highlighted state because alerts and modal dialogs are always displayed 
in the frontmost window. PlainDBox and altDBoxProc are variations of 

dBoxProc: plainDBox is just a plain box with no inner border, and altDBoxProc 
has a two-pixel-thick shadow instead of a border. 


The rDocProc type of window is like a document window with no grow region, with 
rounded corners, and with a method of highlighting that inverts the entire title 
bar (that is, changes white to black and vice versa). It's often used for desk 
accessories. Rounded-corner windows are drawn by the QuickDraw procedure 
FrameRoundRect, which requires the diameters of curvature to be passed as 
parameters. For an rDocProc type of window, the diameters of curvature are both 
16. You can add a number from 1 to 7 to rDocProc to get different diameters: 


Window definition ID Diameters of curvature 
rDocProc 16, 16 
rDocProc + 1 4, 4 
rDocProc + 2 6, 6 
rDocProc + 3 8, 8 
rDocProc + 4 10, 10 
rDocProc + 5 12, 12 
rDocProc + 6 20, 20 
rDocProc + 7 24, 24 


To create a window, the Window Manager needs to know not only the window 
definition ID but also other information specific to this window, such as its 
title (if any), its location, and its plane. You can supply all the needed 
information in individual parameters to a Window Manager routine or, better yet, 
you can store it as a single resource in a resource file and just pass the 
resource ID. This type of resource is called a window template. Using window 
templates simplifies the process of creating a number of windows of the same 
type. More important, it allows you to isolate specific window descriptions from 
your application's code. Translation of window titles to another language, for 
example, would require only a change to the resource file. 
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WINDOW RECORDS 


The Window Manager keeps all the information it requires for its operations ona 
particular window in a window record. The window record contains the following: 


The grafPort for the window. 

A handle to the window definition function. 

A handle to the window's title, if any. 

The window class, which tells whether the window is a system window, 

a dialog or alert window, or a window created directly by the 

application. 

e A handle to the window's control list, which is a list of all the 
controls, if any, in the window. The Control Manager maintains this 
list. 

e A pointer to the next window in the window list, which is a list of 

all windows on the desktop ordered according to their front-to-back 

positions. 


eeee 


The window record also contains an indication of whether the window is currently 
visible or invisible. These terms refer only to whether the window is drawn in 
its plane, not necessarily whether you can see it on the screen. If, for 
example, it's completely overlapped by another window, it's still "visible" even 
though it can't be seen in its current location. 


The 32-bit reference value field of the window record is reserved for use by 
your application. You specify an initial reference value when you create a 
window, and can then read or change the reference value whenever you wish. For 
example, it might be a handle to data associated with the window, such as a 
TextEdit edit record. 


Finally, a window record may contain a handle to a QuickDraw picture of the 
window contents. For a window whose contents never change, the application can 
simply have the Window Manager redraw this picture instead of using the update 
event mechanism. For more information, see "How a Window is Drawn". 


The data type for a window record is called WindowRecord. A window record is 
referred to by a pointer, as discussed further under "Window Pointers" below. 
You can store into and access most of the fields of a window record with Window 
Manager routines, so normally you don't have to know the exact field names. 
Occasionally—particularly if you define your own type of window—you may need to 
know the exact structure; it's given below under "The WindowRecord Data Type". 


Window Pointers 


There are two types of pointer through which you can access windows: WindowPtr 
and WindowPeek. Most programmers will only need to use WindowPtr. 


The Window Manager defines the following type of window pointer: 
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TYPE WindowPtr = GrafPtr; 


It can do this because the first field of a window record contains the window's 
grafPort. This type of pointer can be used to access fields of the grafPort or 
can be passed to QuickDraw routines that expect pointers to grafPorts as 
parameters. The application might call such routines to draw into the window, 
and the Window Manager itself calls them to perform many of its operations. The 
Window Manager gets the additional information it needs from the rest of the 
window record beyond the grafPort. 


In some cases, however, a more direct way of accessing the window record may be 
necessary or desirable. For this reason, the Window Manager also defines the 
following type of window pointer: 


TYPE WindowPeek = “WindowRecord; 


Programmers who want to access WindowRecord fields directly must use this type 
of pointer (which derives its name from the fact that it lets you "peek" at the 
additional information about the window). A WindowPeek pointer is also used 
wherever the Window Manager will not be calling QuickDraw routines and will 
benefit from a more direct means of getting to the data stored in the window 
record. 
Assembly-language note: From assembly language, of course, there's no type 
checking on pointers, and the two types of pointer 
are equal. 


The WindowRecord Data Type 
The exact data structure of a window record is as follows: 


TYPE WindowRecord = RECORD 


port: GrafPort; {window's grafPort} 

windowKind: INTEGER; {window class} 

visible: BOOLEAN; {TRUE if visible} 

hilited: BOOLEAN; {TRUE if highlighted} 

goAwayFlag: BOOLEAN; {TRUE if has go-away region} 

spareFlag: BOOLEAN; {reserved for future use} 

strucRgn: RgnHandle; {structure region} 

contRgn: RgnHandle; {content region} 

updateRgn: RgnHandle; {update region} 

windowDefProc: Handle; {window definition function} 

dataHandle: Handle; {data used by windowDefProc} 

titleHandle: StringHandle; {window's title} 

titleWidth: INTEGER; {width of title in pixels} 

controlList: ControlHandle; {window's control list} 

nextWindow: WindowPeek; {next window in window List} 

windowPic: PicHandle; {picture for drawing window} 

refCon: LONGINT {window's reference value} 
END; 


The port is the window's grafPort. 
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WindowKind identifies the window class. If negative, it means the window is a 
system window (it's the desk accessory's reference number, as described in the 
Desk Manager chapter). It may also be one of the following predefined constants: 


CONST dialogKind 
userKind 


2; {dialog or alert window} 
8; {window created directly by the application} 


DialogKind is the window class for a dialog or alert window, whether created by 
the system or indirectly (via the Dialog Manger) by your application. UserKind 
represents a window created directly by application calls to the Window Manager; 
for such windows the application can in fact set the window class to any value 
greater than 8 if desired. 


Note: WindowKind values 0, 1, and 3 through 7 are reserved for future 
use by the system. 


When visible is TRUE, the window is currently visible. 


Hilited and goAwayFlag are checked by the window definition function when it 
draws the window frame, to determine whether the window should be highlighted 
and whether it should have a go-away region. For a document window, this means 
that if hilited is TRUE, the title bar of the window is highlighted, and if 
goAwayFlag is also TRUE, a close box appears in the highlighted title bar. 


Note: The Window Manager sets the visible and hilited flags to TRUE by 
storing 255 in them rather than 1. This may cause problems in Lisa 
Pascal; to be safe, you should check for the truth or falsity of 
these flags by comparing ORD of the flag to 0. For example, you would 
check to see if the flag is TRUE with ORD(myWindow*.visible) <> 0. 


StrucRgn, contRgn, and updateRgn are region handles, as defined in QuickDraw, to 
the structure region, content region, and update region of the window. These 
regions are all in global coordinates. 


WindowDefProc is a handle to the window definition function for this type of 
window. When you create a window, you identify its type with a window definition 
ID, which is converted into a handle and stored in the windowDefProc field. 
Thereafter, the Window Manager uses this handle to access the definition 
function; you should never need to access this field directly. 


Note: The high-order byte of the windowDefProc field contains some 
additional information that the Window Manager gets from the 
window definition ID; for details, see the section "Defining 
Your Own Windows". 


eeeClick on the X-Ref button, and refer to Technical Note #212.¢e¢e 


DataHandle is reserved for use by the window definition function. If the window 
is one of your own definition, your window definition function may use this 
field to store and access any desired information. If no more than four bytes of 
information are needed, the definition function can store the information 
directly in the dataHandle field rather than use a handle. For example, the 
definition function for rounded-corner windows uses this field to store the 
diameters of curvature. 
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TitleHandle is a string handle to the window's title, if any. 


TitleWidth is the width, in pixels, of the window's title in the system font and 
system font size. This width is determined by the Window Manager and is normally 
of no concern to the application. 


ControlList is a control handle to the window's control list. The ControlHandle 
data type is defined in the Control Manager. 


NextWindow is a pointer to the next window in the window list, that is, the 
window behind this window. If this window is the farthest back (with no windows 
between it and the desktop), nextWindow is NIL. 


Assembly-language note: The global variable WindowList contains a pointer 
to the first window in the window list. Remember 
that any window in the list may be invisible. 


WindowPic is a handle to a QuickDraw picture of the window contents, or NIL if 
the application will draw the window contents in response to an update event, as 
described below under "How a Window is Drawn". 


RefCon is the window's reference value field, which the application may store 
into and access for any purpose. 


Note: Notice that the go-away, drag, and grow regions are not included 
in the window record. Although these are conceptually regions, 
they don't necessarily have the formal data structure for regions 
as defined in QuickDraw. The window definition function determines 
where these regions are, and it can do so with great flexibility. 
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COLOR WINDOW RECORDS 


The Window Manager keeps all the information required for drawing color windows 
in a color window record. The structure and size of a color window record are 
the same as a regular window record, except that it's now optionally based on a 
cGrafPort instead of an old-style grafPort. This allows the window structure and 
content to use the color capability of the Macintosh II. 


ALL standard window definition procedures can now draw window structure 
information into a color window port, called the WMgrCPort. The WMgrCPort is 
analogous to the WMgrPort. See the section "Defining Your Own Windows" for more 
information on how to use the WMgrCPort correctly. 


The new data type CWindowRecord is identical to the old WindowRecord except that 
its port field is a cGrafPort instead of a grafPort. Because both types of port 
are the same size and follow the same rules, the old-style and new-style window 
records are also the same size and have all their fields at the same locations 
within the record. You can access most of the fields of a window record with 
Window Manager routines, so for most applications you won't need to use the 
fields listed below. 


TYPE 

CWindowPtr = CGrafPtr; 

CWindowPeek = “CWindowRecord; 

CWindowRecord = RECORD {all fields remain the same as before} 
port: CGrafPort; {window's CGrafPort} 
windowKind: INTEGER; {window class} 
visible: BOOLEAN; {TRUE if visible} 
hilited: BOOLEAN; {TRUE if highlighted} 
goAwayFlag: BOOLEAN; {TRUE if has go-away region} 
spareF lag: BOOLEAN; {reserved for future use} 
strucRgn: RgnHandle; {structure region} 
contRgn: RgnHandle; {content region} 
updateRgn: RgnHandle; {update region} 
windowDefProc: Handle; {window definition function} 
dataHandle: Handle; {data used by windowDefProc} 
titleHandle: StringHandle; {window's title} 
titleWidth: INTEGER; {width of title in pixels} 
controlList: ControlHandle; {window's control list} 
nextWindow: CWindowPeek; {next window in window List} 
windowPic: PicHandle; {picture for drawing window} 
refCon: LONGINT {window's reference value} 

END; 


ALL of the old Window Manager routines now accept a CWindowPtr in place of a 
WindowPtr. If necessary, high-level languages may use type coercion to convert 
one data type to another. (Another method that allows the use of both types is 
to define a duplicate set of interfaces, substituting a CWindowPtr for a 
WindowPtr for convenience or code efficiency.) The two types of window may even 
be mixed on the same screen; the Window Manager will examine each window's port 
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field to see which type it is, and draw it in full RGB colors or the original 
eight QuickDraw colors. 


Auxiliary Window Records 


As described earlier in this chapter, windows consist of two parts: a structure 
region that includes the frame, titlebar, and other window elements, and a 
content region enclosed within the frame. Applications draw within the content 
region, and may draw in color by using the NewCWindow routine. Use of the 
NewWindow routine limits drawing within the contents region to the eight 
original QuickDraw colors. On the Macintosh II, the structure region is always 
drawn in the WMgrCPort and has full color capability, independent of the content 
region. 


A new data structure, the auxiliary window record, stores the color information 
needed for each color window in an independent list. A number of auxiliary 
window records may exist as a linked list, beginning in the global variable 
AuxWindowHead. Each auxiliary window record is a relocatable object residing in 
the application heap. Figure 5 shows an example of a set of auxiliary window 
records that could be used for an application using a separate window color 
table for each of the windows. This data structure is known as the AuxWinList, 
and is simply a linked list where each additional auxiliary window record points 
to the one after it. 


first AuxRec second Auxkec default Rec 


Au Yin ead Me acybtext—£-oe ayhext ——i—e awhNext—e—e NIL 


aw Woe awe aa VeL 

aan Table aa able ar lable 

dialoz Cltem didlos Cltem dialosCltem 

awF lags awl lags av lags 

awReserved awheserved awheserved 

awhet Con awhet lon awhetlon 
first gecord default 
widow's window's MolorTable 
PolorTable ColorTable 


Figure 5-An AurWinList Stroctore 
Figure 5—An AuxWinList Structure 


The AuxWinRec structure includes a handle to the window's individual color table 
(see "Window Color Tables" below), as well as the handle to the dialogCItem 
list. The rest of the record consists of a link to the next record in the list, 
a pointer to the owning window, and several reserved fields. 


TYPE 
AuxWinHandle = “*AuxWinPtr; 
AuxWinPtr = “AuxWinRec; 
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AuxWinRec = RECORD 

awNext: AuxWinHandle; {handle to next record in list} 
awOwner: WindowPtr; {pointer to owning window} 
awCTable: CTabHandle; {handle to window's color table} 
dialogCItem: Handle; {private storage for } 

{ Dialog Manager} 
awF lags: LONGINT; {reserved for future use} 
awReserved: CTabHandle; {reserved for future use} 
awRefCon: LONGINT {reserved for } 

{ application use} 

END; 


Field descriptions 


awNext The awNext field is a handle to the next record in the auxiliary 
window list. If this record is the default auxWinRec, this value 
will be NIL. 

awOwner The awOwner field is a pointer to the window to which this 
record belongs. The default auxWinRec awOwner field is always 
set to NIL. 

awCTable The awCTable is a handle to the window's color table. Normally 
these are five-element color tables (see "Window Color Tables" 
below). 

dialogCItem The dialogCItem field contains private storage for the 
Dialog Manager. 

awF lags The awFlags field is reserved for future expansion. 

awReserved The awReserved field is reserved for future expansion. 

awRefCon The awRefCon field is a reference constant for use by 


the application. 


The default colors for all windows are loaded from a 'wctb' resource = 0 when 
InitWindows is called. First the application is checked for a ‘wctb' resource, 
then if none is found, the System file is checked, and finally, ROM Resources is 
checked for an existing 'wctb'. To change the default colors for any of the 
windows, use SetWinColor. The standard colors on the system are identical to 
black-and-white Macintosh windows. 


An AuxWinRec specifies the default colorTable for the application's window list. 
For most types of applications, several windows can use the same auxiliary 
window record and share the same color table. Separate auxiliary window records 
are needed only for windows whose color usage differs from the default. Each 
such nonstandard window must have its own auxiliary record, even if it uses the 
same colors as another window. Two or more auxiliary records may share the same 
color table. If a window uses a color table resource, the resource must not be 
purgeable, and the color table won't be disposed when DisposeWindow is called. 
However, for an auxiliary record using any color table that is not a resource, 
the application must avoid deallocating the color table if another window is 
still using it. 


The AuxWinRec is deallocated when DisposeWindow is called. If the resource bit 
of a color table's handle is set, the color table can only be disposed using the 
Resource Manager routine ReleaseResource. 


A window created with the NewWindow routine will initially have no auxiliary 
window record. If it is to use nonstandard colors, it must be given an auxiliary 
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record and a color table with SetWinColor (see the "Window Manager Routines" 
section). Such a window should normally be made invisible at creation and then 
displayed with ShowWindow or ShowHide after the colors are set. For windows 
created from a template resource, the color table can be specified as a resource 


as well. 


A/UX systems: For systems using 32-bit mode, each window will have an 
AuxWinRec. The default AuxWinRec structure is present at 
the end of the AuxWinList, but is not used. The variant 
code for the window is no longer stored in the high byte 
of the windowDefProc field, but is stored in the awFlags 
field. This allows the defproc to occur anywhere within 
the 32-bit address space. 
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WINDOW COLOR TABLES 


The contents and meaning of a window's color table are determined by its window 
definition function (see the "Defining Your Own Windows" section later in this 
chapter). The CTabHandle parameter used in the Window Manager routines provides 
a handle to the window color table. The color table containing the window's 
colorSpecs can have any number of entries, but standard window color tables as 
stored in the system resource file have five colorSpecs. 


The components of a window color table are defined as follows: 


TYPE 

WCTabHandle = “WCTabPtr; 

wWCTabPtr = “WinCTab; 

WinCTab = RECORD 
wCSeed: LONGINT; {unique identifier from table} 
wCReserved: INTEGER; {not used for windows} 
ctSize: INTEGER; {number of entries in table —1} 
ctTable: Array [0..4] of ColorSpec; {array of } 

{ ColorSpec records} 
END; 


Field descriptions 


wCSeed The wCSeed field is unused in window color tables, and is 
reserved for Apple's use. 

wCReserved The wCReserved field is unused in window color tables, and is 
reserved for Apple's use. 

ctSize The ctSize field defines the number of elements in the table, 


minus one. If your application is building a color table for 
use with the standard definition procedure, this field is always 
4. Custom window definition procedures can allocate color tables 
of any size. 

ctTable The ctTable field is made of an array of colorSpec records. 
Each colorSpec contains the partIdentifer and partRGB field, 
as shown below. The partIdentifier field holds an integer which 
associates a colorSpec to a particular part of the window. The 
definition procedures attempt to find the appropriate 
partIdentifier when preparing to draw a part. If that 
partIdentifier is not found, the first color in the table is 
used to draw the part. The partIdentifiers can appear in any 
order in the table. The partRGB field specifies a standard RGB 
color record, indicating what RGB value will be used to draw 
the window part found in partIdentifier. 


The standard window type uses a five-element color table with part identifiers 
as shown in Figure 6. 
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Figure 6—A Window Color Table 


The following constants are used for the partIdentifiers in a window color 
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The default color table read into the heap at application startup simply 
contains the right combination of black and white to produce standard 
black-and-white Macintosh windows. The last record in the auxiliary window list 
holds a handle to this default color table. Before drawing a window, the 
standard window definition function searches the list for an auxiliary record 
whose awOwner points to the window to be drawn. If it finds such a record, it 
uses the color table designated by that record; if it doesn't find one before 
reaching the default record at the end of the list, it uses the default color 
table instead. The default record is recognized by NIL values in both its awNext 
and awOwner fields; your program must not change these fields. 


When creating a color window, the background color is set to the content color. 
Old-style windows should use a content color of white. 
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A nonstandard window definition function can explicitly declare a color table of 
any desired size and define its contents in any way it wishes, except that part 
identifiers 1 to 127 are reserved for system definition. For compatibility with 
the defaulting mechanism described above, the customized definition function 
should either use indices 0 to 4 in the standard way, or else bypass the default 
by allocating an explicit auxiliary record for every window it creates. To 
access a nonstandard window color table from Pascal, the handle must be coerced 
to WCTabHandle. 


The 'wctb' resource is an exact image of the window table data structure. This 
resource is stored in a similar format as 'clut' color table resources. The 
partIdentifier and partCode fields are stored as the colorSpec.value and 
colorSpec.RGBColor fields. 
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HOW A WINDOW IS DRAWN 


When a window is drawn or redrawn, the following two-step process usually takes 
place: The Window Manager draws the window frame, then the application draws 
the window contents. 


To perform the first step of this process, the Window Manager calls the window 
definition function with a request that the window frame be drawn. It 
manipulates regions of the Window Manager port as necessary before calling the 
window definition function, to ensure that only what should and must be drawn is 
actually drawn on the screen. Depending on a parameter passed to the routine 
that created the window, the window definition function may or may not draw a 
go-away region in the window frame (a close box in the title bar, for a document 
window) . 


Usually the second step is that the Window Manager generates an update event to 
get the application to draw the window contents. It does this by accumulating in 
the update region the areas of the window's content region that need updating. 
The Toolbox Event Manager periodically checks to see if there's any window whose 
update region is not empty; if it finds one, it reports (via the GetNextEvent 
function) that an update event has occurred, and passes along the window pointer 
in the event message. (If it finds more than one such window, it issues an 
update event for the frontmost one, so that update events are reported in front- 
to-back order.) The application should respond as follows: 


1. Call BeginUpdate. This procedure temporarily replaces the visRgn of 
the window's grafPort with the intersection of the visRgn and the 
update region. It then sets the update region to an empty region; 
this "clears" the update event so it won't be reported again. 

2. Draw the window contents, entirely or in part. Normally it's more 
convenient to draw the entire content region, but it suffices to 
draw only the visRgn. In either case, since the visRgn is limited 
to where it intersects the old update region, only the parts of the 
window that require updating will actually be drawn on the screen. 

3. Call EndUpdate, which restores the normal visRgn. 


Figure 7 illustrates the effect of BeginUpdate and EndUpdate on the visRgn and 
update region of a window that's redrawn after being brought to the front. 


If you choose to draw only the visRgn in step 2, there are various ways you can 
check to see whether what you need to draw falls in that region. With the 
QuickDraw function PtInRgn, you can check whether a point lies in the visRgn. It 
may be more convenient to look at the visRgn's enclosing rectangle, which is 
stored in its rgnBBox field. The QuickDraw functions PtInRect and SectRect let 
you check for intersection with a rectangle. 


To be able to respond to update events for one of its windows, the application 
has to keep track of the window's contents, usually in a data structure. In most 
cases, it's best never to draw immediately into a window; when you need to draw 
something, just keep track of it and add the area where it should be drawn to 
the window's update region (by calling one of the Window Manager's update region 
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maintenance routines, InvalRect and InvalRgn). Do the actual drawing only in 
response to an update event. Usually this will simplify the structure of your 
application considerably, but be aware of the following possible problems: 


¢ This method doesn't work if you want to do continuous scrolling while 
the user presses a scroll arrow; in this case, you would draw directly 
into the window. 

« This method isn't convenient to apply to areas that aren't easily 
defined by a rectangle or a region; again, just draw directly into the 
window. 

¢ If you find that sometimes there's too long a delay before an update 
event happens, you can get update events first when necessary by 
calling GetNextEvent with a mask that accepts only that type of event. 


The Window Manager allows an alternative to the update event mechanism that may 
be useful for windows whose contents never change: A handle to a QuickDraw 
picture may be stored in the window record. If this is done, the Window Manager 
doesn't generate an update event to get the application to draw the window 
contents; instead, it calls the QuickDraw procedure DrawPicture to draw the 
picture whose handle is stored in the window record (and it does all the 
necessary region manipulation). 


W hel changes to 
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Figure 7-Updating Window Contents 
Figure 7—-Updating Window Contents 
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MAKING A WINDOW ACTIVE: ACTIVATE EVENTS 


A number of Window Manager routines change the state of a window from inactive 
to active or from active to inactive. For each such change, the Window Manager 
generates an activate event, passing along the window pointer in the event 
message. The activeFlag bit in the modifiers field of the event record is set if 
the window has become active, or cleared if it has become inactive. 


When the Toolbox Event Manager finds out from the Window Manager that an 
activate event has been generated, it passes the event on to the application 
(via the GetNextEvent function). Activate events have the highest priority of 
any type of event. 


Usually when one window becomes active another becomes inactive, and vice versa, 
so activate events are most commonly generated in pairs. When this happens, the 
Window Manager generates first the event for the window becoming inactive, and 
then the event for the window becoming active. Sometimes only a single activate 
event is generated, such as when there's only one window in the window list, or 
when the active window is permanently disposed of (since it no longer exists). 


Activate events for dialog and alert windows are handled by the Dialog Manager. 
In response to activate events for windows created directly by your application, 
you might take actions such as the following: 


¢ In a document window containing a size box or scroll bars, erase the 
Size box icon or scroll bars when the window becomes inactive and 
redraw them when it becomes active. 

« In a window that contains text being edited, remove the highlighting 
or blinking vertical bar from the text when the window becomes inactive 
and restore it when the window becomes active. 

¢ Enable or disable a menu or certain menu items as appropriate to match 
what the user can do when the window becomes active or inactive. 


Assembly-language note: The global variable CurActivate contains a 
pointer to a window for which an activate event 
has been generated; the event, however, may not 
yet have been reported to the application via 
GetNextEvent, so you may be able to keep the event 
from happening by clearing CurActivate. Similarly, 
you may be able to keep a deactivate event from 
happening by clearing the global variable CurDeactive. 
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USING THE WINDOW MANAGER 


To use the Window Manager, you must have previously called InitGraf to 
initialize QuickDraw and InitFonts to initialize the Font Manager. The first 
Window Manager routine to call is the initialization routine InitWindows, which 
draws the desktop and the (empty) menu bar. 


Where appropriate in your program, use NewWindow or GetNewWindow to create any 
windows you need; these functions return a window pointer, which you can then 
use to refer to the window. NewWindow takes descriptive information about the 
window from its parameters, whereas GetNewWindow gets the information from a 
window template in a resource file. You can supply a pointer to the storage for 
the window record or let it be allocated by the routine creating the window; 
when you no longer need a window, call CloseWindow if you supplied the storage, 
or DisposeWindow if not. 


When the Toolbox Event Manager function GetNextEvent reports that an update 
event has occurred, call BeginUpdate, draw the visRgn or the entire content 
region, and call EndUpdate (see "How a Window is Drawn"). You can also use 
InvalRect or InvalRgn to prepare a window for updating, and ValidRect or 
ValidRgn to protect portions of the window from updating. 


When drawing the contents of a window that contains a size box in its content 
region, you'll draw the size box if the window is active or just the lines 
delimiting the size box and scroll bar areas if it's inactive. The FrontWindow 
function tells you which is the active window; the DrawGrowIcon procedure helps 
you draw the size box or delimiting lines. You'll also call the latter procedure 
when an activate event occurs that makes the window active or inactive. 


Note: Before drawing in a window or making a call that affects the update 
region, remember to set the window to be the current grafPort with 
the QuickDraw procedure SetPort. 


When GetNextEvent reports a mouse-down event, call the FindWindow function to 
find out which part of which window the mouse button was pressed in. 


e If it was pressed in the content region of an inactive window, make 
that window the active window by calling SelectWindow. 

e If it was pressed in the grow region of the active window, call 
GrowWindow to pull around an image that shows how the window's size 
will change, and then SizeWindow to actually change the size. 

e If it was pressed in the drag region of any window, call DragWindow, 
which will pull an outline of the window across the screen, move the 
window to a new location, and, if the window is inactive, make it the 
active window (unless the Command key was held down). 

« If it was pressed in the go-away region of the active window, call 
TrackGoAway to handle the highlighting of the go-away region and to 
determine whether the mouse is inside the region when the button is 
released. Then do whatever is appropriate as a response to this mouse 
action in the particular application. For example, call CloseWindow or 
DisposeWindow if you want the window to go away permanently, or 
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HideWindow if you want it to disappear temporarily. 


Note: If the mouse button was pressed in the content region of an 
active window (but not in the grow region), call the Control 
Manager function FindControl if the window contains controls. 
If it was pressed in a system window, call the Desk Manager 
procedure SystemClick. See the Control Manager and Desk Manager 
chapters for details. 


The MoveWindow procedure simply moves a window without pulling around an outline 
of it. Note, however, that the application shouldn't surprise the user by moving 
(or sizing) windows unexpectedly. There are other routines that you normally 
won't need to use that let you change the title of a window, place one window 
behind another, make a window visible or invisible, and access miscellaneous 
fields of the window record. There are also low-level routines that may be of 
interest to advanced programmers. 


A new variation of the window definition function implements a feature known as 
window zooming; a description of window zooming is found in the Macintosh User 
Interface Guidelines chapter. 


If you're using the standard document window, you can implement a zoom-window 
box by specifying a window definition function with a resource ID of 0 and a 
variation code of 8 when you call either the NewWindow or GetNewWindow 
functions. Two fields in the window record, dataHandle and spareFlag, are used 
only when variation code 8 is specified (otherwise they're not used). 


DataHandle contains a handle to two rectangles that specify the standard and 
user states of the window: 


TYPE 
WStateData = RECORD; 
userState: Rect; 
stdState: Rect 
END; 


If you wish, your application can access both states. You might want to provide 
initial values for the user state. Or you might want to save and restore all 
windows to the same state the next time your application is launched. To do 
this, you would save the two states and determine which of the two is current. 
The next time the application is launched, you would then create the window 
using the saved current state, and set the user and standard states to their 
previous values, after the GetNewWindow or NewWindow call. 


SpareFlag is TRUE if zooming has been requested (that is, if a variation code of 
8 has been specified). 


If you create a custom window, you can give your window definition function any 
variation code you wish. If you want to implement zooming in the custom window, 
you must supply values for WStateData. 


When there's a mouse-down event in the zoom-window box and your application 
calls the FindWindow function, the integer returned will be one of the following 
predefined constants: 
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CONST inZoomiIn 
inZoom0ut 


7; {in zoom box for zooming in} 
8; {in zoom box for zooming out} 


InZoomIn and inZoomOut both indicate that the mouse button was pressed in the 
zoom-window box of the window. FindWindow returns inZoomIn when the window is in 
the standard state (and will be zoomed in), and inZoomOut when it's in the user 
state (and will be zoomed out). 


If either of these constants are returned by FindWindow, call the TrackBox 
function (described below) to handle the highlighting of the zoom-window box and 
to determine whether the mouse is inside the box when the button is released. If 
TrackBox returns TRUE, call the ZoomWindow procedure (described below) to resize 
the window appropriately. 


Advanced programmers: Two additional constants have been defined for your 
window definition function to return in response to 
a wHit message: 


CONST winZoomin 
wiInZoomOut 


5; {in zoom box for zooming in} 
6; {in zoom box for zooming out} 
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USING COLOR WINDOWS 


Each color window (excluding those using a colored default) should have its own 
color table. When an application is initialized, the default colorTable field 
used is the 'wctb' resource = @ in the application's resource fork. This allows 
you to set default window colors on an application basis. If a '‘wctb' 

resource = @ is not found in the application, or in the System file, a 
nonchangeable resource is loaded from ROM resources. Normally, the default 
window colors will be the correct combination of black and white to create 
standard Macintosh windows. 


The GetAuxWin routine is used to return the handle to an individual window color 
table. CloseWindow will dispose of a window's AuxWinRec, if present. 


When a new window is created with the NewCWindow or NewWindow routine, no entry 
is added to the AuxList, and the window will use the default colors. If 
SetWinColor is used with a different color table for a window, a new AuxList 
will be allocated and added to the head of the list. To avoid having a visible 
window flash to a different color, it is useful to call NewCWindow or NewWindow 
with the visible field set to FALSE, then to call SetWinColor to change the 
colors, and finally to call ShowHide to make it visible. 


Within an application, a new window is usually created from a resource by using 
GetNewCWindow or GetNewWindow. GetNewCWindow will attempt to load a ‘wctb' 
resource if it is present. It then executes the SetWinColor call. A new AuxRec 
is allocated if the resource file contains the 'wctb' resource with the same 
ResId as the 'WIND' template. Otherwise, the default window colors are used. The 
Window Manager automatically hides specially-colored visible windows so that 
they won't flash to a different color. 


Any windows created with NewWindow will contain an old-style grafPort in the 
windowRec, and only the eight original QuickDraw colors can be displayed in the 
window content. NewCWindow creates a window record based on a cGrafport, thus 
allowing full use of the Macintosh II color capability. 


Advanced Window Manager routines include SetDeskCPat, which allows the Control 
Panel to set the desktop pattern to a color pattern. This routine should not be 
used in application programs, but its description here will help you understand 
how the Window Manager manages desktop patterns. The GetCWMgrPort routine 
returns the address of the WMgrCPort. In most cases this won't be necessary, 
since applications should avoid drawing in the Window Manager ports. 


Color QuickDraw on the Macintosh II supports drawing to multiple screens that 
have been configured to act as a single large screen. All window dragging and 
sizing operations, including the MoveWindow, DragGrayRgn, GrowWindow, 
SizeWindow, and ZoomWindow routines, have been modified to allow windows to 
perform properly when dragged across a multiple-screen desktop. If a portion of 
a window moves across screen boundaries, update events are automatically 
generated to ensure that the window's contents are drawn in the correct colors. 
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A special Window Manager variable, the GrayRgn, describes the size and shape of 
the desktop on all Macintoshes. On a multiple-screen Macintosh II, the GrayRgn 
variable contains information on all the screens configured into the system. 
Your application can determine the size of the desktop by checking the 
GrayRgn's bounding box, and should use this rectangle for dragging and sizing 
bounds. The GetGrayRgn routine returns a handle to the current desktop GrayRgn. 
Zooming should be restricted to using the full size of only one screen by using 


screenbits.bounds for the main screen, or the appropriate GDRect for any other 
screens. 
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WINDOW MANAGER ROUTINES 


Initialization and Allocation 
PROCEDURE InitWindows; [Macintosh Plus, Macintosh SE, Macintosh II] 


InitWindows initializes the Window Manager. It creates the Window Manager port; 
you can get a pointer to this port with the GetWMgrPort procedure. InitWindows 
draws the desktop (as a rounded-corner rectangle with diameters of curvature 
16,16, in the desktop pattern) and the (empty) menu bar. Call this procedure 
once before all other Window Manager routines. 


Note: The desktop pattern is the pattern whose resource ID is: 
CONST deskPatID = 16; 


If you store a pattern with resource ID deskPatID in the application's 
resource file, that pattern will be used whenever the desktop is drawn. 


The InitWindow procedure now calls the new Menu Bar definition procedure to 
calculate menu bar height, and to draw the empty menu bar. Since the menu bar 
definition procedure ('MBDF') actually performs these calculations, InitWindows 
now calls InitMenus directly. InitMenus has been modified so that it can be 
called twice in a program without ill effect. 


For the Macintosh II, if the color desktop pattern is enabled, InitWindows loads 
the default desktop pixel pattern as well as the standard binary pattern. It 
allocates both the WMgrCPort and the WMgrPort, then calculates the union of all 
active screen devices, and saves this region in the global variable GrayRgn. 


Warning: InitWindows creates the Window Manager port as a nonrelocatable 
block in the application heap. To prevent heap fragmentation, 
call InitWindows in the main segment of your program, before any 
references to routines in other segments. 


Assembly-language note: InitWindows initializes the global variable GrayRgn 
to be a handle to the desktop region (a rounded-corner 
rectangle occupying the entire screen, minus the menu 
bar), and draws this region. It initializes the global 
variable DeskPattern to the pattern whose resource ID 
is deskPatID, and paints the desktop with this pattern. 
Any subsequent time that the desktop needs to be drawn, 
such as when a new area of it is exposed after a 
window is closed or moved, the Window Manager calls 
the procedure pointed to by the global variable 
DeskHook, if any (normally DeskHook is 0). The 
DeskHook procedure is called with 0 in register DO 
to distinguish this use of it from its use in 
responding to clicks on the desktop (discussed in the 
description of FindWindow); it should respond by 
painting thePort*.clipRgn with DeskPattern and then 
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doing anything else it wants. 
PROCEDURE GetWMgrPort (VAR wPort: GrafPtr); 
GetwMgrPort returns in wPort a pointer to the Window Manager port. 


Warning: Do not change any regions of the Window Manager port, or 
overlapping windows may not be handled properly. 


Assembly-language note: This pointer is stored in the global variable 
WMgrPort. 


FUNCTION NewWindow (wStorage: Ptr; boundsRect: Rect; title: Str255; 
visible: BOOLEAN; procID: INTEGER; behind: WindowPtr; 
goAwayFlag: BOOLEAN; refCon: LONGINT) : WindowPtr; 


NewWindow creates a window as specified by its parameters, adds it to the window 
list, and returns a windowPtr to the new window. It allocates space for the 
structure and content regions of the window and asks the window definition 
function to calculate those regions. 


WStorage is a pointer to where to store the window record. For example, if 
you've declared the variable wRecord of type WindowRecord, you can pass @wRecord 
as the first parameter to NewWindow. If you pass NIL for wStorage, the window 
record will be allocated as a nonrelocatable object in the heap; in that case, 
though, you risk ending up with a fragmented heap. 


BoundsRect, a rectangle given in global coordinates, determines the window's 
size and location, and becomes the portRect of the window's grafPort; note, 
however, that the portRect is in local coordinates. NewWindow sets the top left 
corner of the portRect to (0,0). For the standard types of windows, the 
boundsRect defines the content region of the window. 


Note: The bit map, pen pattern, and other characteristics of the window's 
grafPort are the same as the default values set by the OpenPort 
procedure in QuickDraw, except for the character font, which is set 
to the application font rather than the system font. (NewWindow 
actually calls OpenPort to initialize the window's grafPort.) Note, 
however, that the coordinates of the grafPort's portBits.bounds and 
visRgn are changed along with its portRect. 


The title parameter is the window's title. If the title of a document window is 
longer than will fit in the title bar, it's truncated in one of two ways: If 
the window has a close box, the characters that don't fit are truncated from the 
end of the title; if there's no close box, the title is centered and truncated 
at both ends. 


If the visible parameter is TRUE, NewWindow draws the window. First it calls the 
window definition function to draw the window frame; if goAwayFlag is also TRUE 
and the window is frontmost (as specified by the behind parameter, below), it 
draws a go-away region in the frame. Then it generates an update event for the 
entire window contents. 


ProcID is the window definition ID, which leads to the window definition 
function for this type of window. The function is read into memory if it's not 


@ SpInside Macintosh * Version 1.0 * November 1989 * Apple Computer 
THE WINDOW MANAGER ¢ 32 of 67 


already in memory. If it can't be read, NewWindow returns NIL. The window 
definition IDs for the standard types of windows are Listed above under 
"Windows and Resources". Window definition IDs for windows of your own design 
are discussed later under "Defining Your Own Windows". 


The behind parameter determines the window's plane. The new window is inserted 
in back of the window pointed to by this parameter. To put the new window behind 
all other windows, use behind=NIL. To place it in front of all other windows, 
use behind=POINTER(-1); in this case, NewWindow will unhighlight the previously 
active window, highlight the window being created, and generate appropriate 
activate events. 


RefCon is the window's reference value, set and used only by your application. 


NewWindow also sets the window class in the window record to indicate that the 
window was created directly by the application. 


FUNCTION GetNewWindow (windowID: INTEGER; wStorage: Ptr; 
behind: WindowPtr) : WindowPtr; 


Like NewWindow (above), GetNewWindow creates a window as specified by its 
parameters, adds it to the window list, and returns a windowPtr to the new 
window. The only difference between the two functions is that instead of having 
the parameters boundsRect, title, visible, procID, goAwayFlag, and refCon, 
GetNewWindow has a single windowID parameter, where windowID is the resource ID 
of a window template that supplies the same information as those parameters. If 
the window template can't be read from the resource file, GetNewWindow returns 
NIL. GetNewWindow releases the memory occupied by the resource before returning. 
The wStorage and behind parameters have the same meaning as in NewWindow. 


PROCEDURE CloseWindow (theWindow: WindowPtr); 


CloseWindow removes the given window from the screen and deletes it from the 
window list. It releases the memory occupied by all data structures associated 
with the window, but not the memory taken up by the window record itself. Call 
this procedure when you're done with a window if you supplied NewWindow or 
GetNewWindow a pointer to the window storage (in the wStorage parameter) when 
you created the window. 


Any update events for the window are discarded. If the window was the frontmost 
window and there was another window behind it, the latter window is highlighted 
and an appropriate activate event is generated. 


Warning: If you allocated memory yourself and stored a handle to it in the 
refCon field, CloseWindow won't know about it-—you must release the 
memory before calling CloseWindow. Similarly, if you used the 
windowPic field to access a picture stored as a resource, you must 
release the memory it occupies; CloseWindow assumes the picture 
isn't a resource, and calls the QuickDraw procedure KillPicture to 
delete it. 


PROCEDURE DisposeWindow (theWindow: WindowPtr); 


Assembly-language note: The macro you invoke to call DisposeWindow from 
assembly Language is named DisposWindow. 
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Dispose Window calls CloseWindow (above) and then releases the memory occupied 
by the window record. Call this procedure when you're done with a window if you 
let the window record be allocated in the heap when you created the window (by 
passing NIL as the wStorage parameter to NewWindow or GetNewWindow) . 


Window Display 


These procedures affect the appearance or plane of a window but not its size or 
location. 


PROCEDURE SetWTitle (theWindow: WindowPtr; title: Str255); 


SetWTitle sets theWindow's title to the given string, performing any necessary 
redrawing of the window frame. 


PROCEDURE GetWTitle (theWindow: WindowPtr; VAR title: Str255); 
GetWTitle returns theWindow's title as the value of the title parameter. 
PROCEDURE SelectWindow (theWindow: WindowPtr); 


SelectWindow makes theWindow the active window as follows: It unhighlights the 
previously active window, brings theWindow in front of all other windows, 
highlights theWindow, and generates the appropriate activate events. Call this 
procedure if there's a mouse-down event in the content region of an inactive 
window. 


PROCEDURE HideWindow (theWindow: WindowPtr); 


HideWindow makes theWindow invisible. If theWindow is the frontmost window and 
there's a window behind it, HideWindow also unhighlights theWindow, brings the 
window behind it to the front, highlights that window, and generates appropriate 
activate events (see Figure 8). If theWindow is already invisible, HideWindow 
has no effect. 
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Figure 8-Hiding and Showing Document Windows 
Figure 8-Hiding and Showing Document Windows 
PROCEDURE ShowWindow (theWindow: WindowPtr); 


ShowWindow makes theWindow visible. It does not change the front-to-back 
ordering of the windows. Remember that if you previously hid the frontmost 
window with HideWindow, HideWindow will have brought the window behind it to the 
front; so if you then do a ShowWindow of the window you hid, it will no longer 
be frontmost (see Figure 8). If theWindow is already visible, ShowWindow has no 
effect. 


Note: Although it's inadvisable, you can create a situation where the 
frontmost window is invisible. If you do a ShowWindow of such a 
window, it will highlight the window if it's not already highlighted 
and will generate an activate event to force this window from inactive 
to active. 


PROCEDURE ShowHide (theWindow: WindowPtr; showFlag: BOOLEAN); 


If showFlag is TRUE, ShowHide makes theWindow visible if it's not already 
visible and has no effect if it is already visible. If showFlag is FALSE, 
ShowHide makes theWindow invisible if it's not already invisible and has no 
effect if it is already invisible. Unlike HideWindow and ShowWindow, ShowHide 
never changes the highlighting or front-to-back ordering of windows or generates 
activate events. 


Warning: Use this procedure carefully, and only in special circumstances 
where you need more control than allowed by HideWindow and 
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ShowWindow. 
PROCEDURE HiliteWindow (theWindow: WindowPtr; fHilite: BOOLEAN); 


If fHilite is TRUE, this procedure highlights theWindow if it's not already 
highlighted and has no effect if it is highlighted. If fHilite is FALSE, 
HiliteWindow unhighlights theWindow if it is highlighted and has no effect if 
it's not highlighted. The exact way a window is highlighted depends on its 
window definition function. 


Normally you won't have to call this procedure, since you should call 
SelectWindow to make a window active, and SelectWindow takes care of the 
necessary highlighting changes. Highlighting a window that isn't the active 
window is contrary to the Macintosh User Interface Guidelines. 


PROCEDURE BringToFront (theWindow: WindowPtr) ; 


BringToFront brings theWindow to the front of all other windows and redraws the 
window as necessary. Normally you won't have to call this procedure, since you 
should call SelectWindow to make a window active, and SelectWindow takes care of 
bringing the window to the front. If you do call BringToFront, however, remember 
to call HiliteWindow to make the necessary highlighting changes. 


PROCEDURE SendBehind (theWindow, behindWindow: WindowPtr); 


SendBehind sends theWindow behind behindWindow, redrawing any exposed windows. 
If behindWindow is NIL, it sends theWindow behind all other windows. If 
theWindow is the active window, it unhighlights theWindow, highlights the new 
active window, and generates the appropriate activate events. 


Warning: Do not use SendBehind to deactivate a previously active window. 
Calling SelectWindow to make a window active takes care of 
deactivating the previously active window. 


Note: If you're moving theWindow closer to the front (that is, if it's 
initially even farther behind behindWindow), you must make the 
following calls after calling SendBehind: 


wPeek := POINTER(theWindow) ; 
PaintOne(wPeek, wPeek*.strucRgn) ; 
CalcVis (wPeek) 


PaintOne and CalcVis are described under "Low-Level Routines". 
FUNCTION FrontWindow : WindowPtr; 


FrontWindow returns a pointer to the first visible window in the window list 
(that is, the active window). If there are no visible windows, it returns NIL. 


Assembly-language note: In the global variable GhostWindow, you can store 
a pointer to a window that's not to be considered 
frontmost even if it is (for example, if you want 
to have a special editing window always present 
and floating above all the others). If the window 
pointed to by GhostWindow is the first window in 
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the window list, FrontWindow will return a pointer 
to the next visible window. 


PROCEDURE DrawGrowlIcon (theWindow: WindowPtr); 


Call DrawGrowIcon in response to an update or activate event involving a window 
that contains a size box in its content region. If theWindow is active, 
DrawGrowlcon draws the size box; otherwise, it draws whatever is appropriate to 
show that the window temporarily cannot be sized. The exact appearance and 
location of what's drawn depend on the window definition function. For an active 
document window, DrawGrowIcon draws the size box icon in the bottom right corner 
of the portRect of the window's grafPort, along with the lines delimiting the 
size box and scroll bar areas (15 pixels in from the right edge and bottom of 
the portRect). It doesn't erase the scroll bar areas, so if the window doesn't 
contain scroll bars you should erase those areas yourself after the window's 
size changes. For an inactive document window, DrawGrowIcon draws only the lines 
delimiting the size box and scroll bar areas, and erases the size box icon. 


Mouse Location 


PROCEDURE FindWindow (thePoint: Point; VAR whichWindow:windowPtr) : INTEGER; 
[Macintosh Plus, Macintosh SE, Macintosh II] 


When a mouse-down event occurs, the application should call FindWindow with 
thePt equal to the point where the mouse button was pressed (in global 
coordinates, as stored in the where field of the event record). FindWindow tells 
which part of which window, if any, the mouse button was pressed in. If it was 
pressed in a window, the whichWindow parameter is set to the window pointer; 
otherwise, it's set to NIL. The integer returned by FindWindow is one of the 
following predefined constants: 


CONST inDesk = 0; {none of the following} 
inMenuBar = 13; {in menu bar} 
inSysWindow = 2; {in system window} 
inContent = 3; {in content region (except grow, if active) } 
inDrag = 4; {in drag region} 
inGrow = 5; {in grow region (active window only) } 
inGoAway = 6; {in go-away region (active window only) } 


InDesk usually means that the mouse button was pressed on the desktop, outside 
the menu bar or any windows; however, it may also mean that the mouse button was 
pressed inside a window frame but not in the drag region or go-away region of 
the window. Usually one of the last four values is returned for windows created 
by the application. 


The FindWindow procedure now calls the new menu bar definition procedure to 
determine whether the point where the mouse button was pressed lies in the menu 
bar. 


Assembly-language note: If you store a pointer to a procedure in the 
global variable DeskHook, it will be called when 
the mouse button is pressed on the desktop. The 
DeskHook procedure will be called with —1 in 
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register DO to distinguish this use of it from its 
use in drawing the desktop (discussed in the 
description of InitWindows). Register AO will 
contain a pointer to the event record for the 
mouse-down event. When you use DeskHook in this 

way FindWindow does not return inDesk when the 
mouse button is pressed on the desktop; it 

returns inSysWindow, and the Desk Manager procedure 
SystemClick calls the DeskHook procedure. 


If the window is a documentProc type of window that doesn't contain a size box, 
the application should treat inGrow the same as inContent; if it's a 
noGrowDocProc type of window, FindWindow will never return inGrow for that 
window. If the window is a documentProc, noGrowDocProc, or rDocProc type of 
window with no close box, FindWindow will never return inGoAway for that window. 


FUNCTION TrackGoAway (theWindow: WindowPtr; thePt: Point) : BOOLEAN; 


When there's a mouse-down event in the go-away region of theWindow, the 
application should call TrackGoAway with thePt equal to the point where the 
mouse button was pressed (in global coordinates, as stored in the where field of 
the event record). TrackGoAway keeps control until the mouse button is released, 
highlighting the go-away region as long as the mouse location remains inside it, 
and unhighlighting it when the mouse moves outside it. The exact way a window's 
go-away region is highlighted depends on its window definition function; the 
highlighting of a document window's close box is illustrated in Figure 9. When 
the mouse button is released, TrackGoAway unhighlights the go-away region and 
returns TRUE if the mouse is inside the go-away region or FALSE if it's outside 
the region (in which case the application should do nothing). 
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Figure 9-A Document Window's Close Bor 
Figure 9-A Document Window's Close Box 


Assembly-language note: If you store a pointer to a procedure in the 
global variable DragHook, TrackGoAway will call 
that procedure repeatedly (with no parameters) for 
as long as the user holds down the mouse button. 


Window Movement and Sizing 
PROCEDURE MoveWindow (theWindow:windowPtr; hGlobal, vGlobal: INTEGER; 
front: BOOLEAN); [Macintosh IT] 
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MoveWindow moves theWindow to another part of the screen, without affecting its 
size or plane. The top left corner of the portRect of the window's grafPort is 
moved to the screen point indicated by the global coordinates hGlobal and 
vGlobal. The local coordinates of the top left corner remain the same. If the 
front parameter is TRUE and theWindow isn't the active window, MoveWindow makes 
it the active window by calling SelectWindow(theWindow) . 


The MoveWindow routine formerly copied a window's entire structure region. On 
multiple-screen systems, MoveWindow now copies only the portion of the window 
that will remain on the same screen. ALL other parts of the window are not 
copied, and are redrawn on the next update event. When a window's content 
crosses screen boundaries, MoveWindow may post additional updates on multiple 
screen systems. 


For new applications, the specified dragging bounds should be the bounding box 
of the GrayRgn. To support existing programs, if the dragging bounds passed to 
MoveWindow are within six pixels of the current screenbits.bounds on the left, 
right, and bottom, and are within thirty-six pixels of the 
screenbits.bounds.top, the GrayRgn's bounding box is substituted. 


PROCEDURE DragWindow (theWindow: WindowPtr; startPt: Point; boundsRect: Rect); 


When there's a mouse-down event in the drag region of theWindow, the application 
should call DragWindow with startPt equal to the point where the mouse button 
was pressed (in global coordinates, as stored in the where field of the event 
record). DragWindow pulls a dotted outline of theWindow around, following the 
movements of the mouse until the button is released. When the mouse button is 
released, DragWindow calls MoveWindow to move theWindow to the location to which 
it was dragged. If theWindow isn't the active window (and the Command key wasn't 
being held down), DragWindow makes it the active window by passing TRUE for the 
front parameter when calling MoveWindow. If the Command key was being held down, 
the window is moved without being made the active window. 


BoundsRect is also given in global coordinates. If the mouse button is released 
when the mouse location is outside the limits of boundsRect, DragWindow returns 
without moving theWindow or making it the active window. For a document window, 
boundsRect typically will be four pixels in from the menu bar and from the other 
edges of the screen, to ensure that there won't be less than a four-pixel-square 
area of the title bar visible on the screen. 


Assembly-language note: As for TrackGoAway, if you store a pointer to a 
procedure in the global variable DragHook, that 
procedure will be called repeatedly while the user 
holds down the mouse button. (DragWindow calls 
DragGrayRgn, which calls the DragHook procedure). 


FUNCTION GrowWindow (theWindow:windowPtr: startPt:Point; 
sizeRect: Rect):LONGINT; [Macintosh ITI] 


When there's a mouse-down event in the grow region of theWindow, the application 
should call GrowWindow with startPt equal to the point where the mouse button 
was pressed (in global coordinates, as stored in the where field of the event 
record). GrowWindow pulls a grow image of the window around, following the 
movements of the mouse until the button is released. The grow image for a 
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document window is a dotted outline of the entire window and also the lines 
delimiting the title bar, size box, and scroll bar areas; Figure 10 illustrates 
this for a document window containing both scroll bars, but the grow image would 
be the same even if the window contained one or no scroll bars. In general, the 
grow image is defined in the window definition function and is whatever is 
appropriate to show that the window's size will change. 


On multiple-screen systems, the GrowWindow routine is modified so that windows 
can be stretched only a small amount onto other screens. This restriction can be 
removed by holding down the command key while growing the window, allowing 
windows to cover the full extent of the multiscreen desktop. 
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Figure 10-GrovVWindoy Operation on a Document Findor 
Figure 10—GrowWindow Operation on a Document Window 


The application should subsequently call SizeWindow to change the portRect of 
the window's grafPort to the new one outlined by the grow image. The sizeRect 
parameter specifies limits, in pixels, on the vertical and horizontal 
measurements of what will be the new portRect. SizeRect.top is the minimum 
vertical measurement, sizeRect.left is the minimum horizontal measurement, 
sizeRect.bottom is the maximum vertical measurement, and sizeRect.right is the 
maximum horizontal measurement. 


GrowWindow returns the actual size for the new portRect as outlined by the grow 
image when the mouse button is released. The high-order word of the long integer 
is the vertical measurement in pixels and the low-order word is the horizontal 
measurement. A return value of 0 indicates that the size is the same as that of 
the current portRect. 


Note: The Toolbox Utility function HiWord takes a long integer as a 
parameter and returns an integer equal to its high-order word; the 
function LoWord returns the low-order word. 
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Assembly-language note: Like TrackGoAway, GrowWindow repeatedly calls the 
procedure pointed to by the global variable DragHook 
(if any) as long as the mouse button is held down. 


PROCEDURE SizeWindow (theWindow: WindowPtr; w,h: INTEGER; fUpdate: BOOLEAN); 


SizeWindow enlarges or shrinks the portRect of theWindow's grafPort to the width 
and height specified by w and h, or does nothing if w and h are 0. The window's 
position on the screen does not change. The new window frame is drawn; if the 
width of a document window changes, the title is again centered in the title 
bar, or is truncated if it no longer fits. If fUpdate is TRUE, SizeWindow 
accumulates any newly created area of the content region into the update region 
(see Figure 11); normally this is what you'll want. If you pass FALSE for 
fUpdate, you're responsible for the update region maintenance yourself. For more 
information, see InvalRect and ValidRect. 
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Figure 11-Size Window Operation on a Document Windor 


Figure 11—-SizeWindow Operation on a Document Window 


FUNCTION TrackBox (theWindow: WindowPtr; thePt: Point; 
partCode: INTEGER) : BOOLEAN; 


When there's a mouse-down event in the zoom-window box of theWindow, the 
application should call TrackBox with thePt equal to the point where the mouse 
button was pressed (in global coordinates, as stored in the where field of the 
event record). The partCode parameter contains the constant (either inZoomIn or 
inZoomOut) returned by FindWindow. TrackBox keeps control until the mouse button 
is released; it highlights the zoom-window box in the same way as a window's 
close box is highlighted. When the mouse button is released, TrackBox 
unhighlights the zoom-window box and returns TRUE if the mouse is inside the 
zoom-window box or FALSE if it's outside the box (in which case the application 
should do nothing). 
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PROCEDURE ZoomWindow(theWindow:windowPtr; partCode: INTEGER; 
front: BOOLEAN); [Macintosh IT] 


Call ZoomWindow after a call to TrackBox that returns TRUE. The partCode 
parameter contains the constant (either inZoomIn or inZoomOut) returned by 
FindWindow. The window will be zoomed either out or in, depending on the state 
of the window specified by partCode. If the window is already in the state 
specified by partCode, ZoomWindow does nothing. If the front parameter is TRUE, 
the window will be brought to the front; otherwise, the window is left where it 
is. (This means a window can be zoomed without necessarily becoming the active 
window. ) 


On multiple-screen systems, applications that call ZoomWindow with a new size 
based on the screen rectangle (screenBits.bounds) will now cause any windows not 
on the main screen to zoom to full size on the main screen. To perform properly 
in a multiscreen environment, these applications should test which screen 
contains the greatest area of the window to be zoomed, and then zoom to the 
screen rectangle (GDRect) for that screen device. See the Graphics Devices 
chapter for information on obtaining the GDRect value for a device. 


For best results, call the QuickDraw procedure EraseRect with the portRect field 
of theWindow's grafPort before calling ZoomWindow. 


Warning: Using the QuickDraw procedure SetPort, set thePort to the window's 
port before calling ZoomWindow. 


Note: ZoomWindow is in no way tied to the TrackBox function and could just 
as easily be called in response to a selection from a menu. 


Update Region Maintenance 
PROCEDURE InvalRect (badRect: Rect); 


InvalRect accumulates the given rectangle into the update region of the window 
whose grafPort is the current port. This tells the Window Manager that the 
rectangle has changed and must be updated. The rectangle is given in local 
coordinates and is clipped to the window's content region. 


For example, this procedure is useful when you're calling SizeWindow for a 
document window that contains a size box or scroll bars. Suppose you're going to 
call SizeWindow with fUpdate=TRUE. If the window is enlarged as shown in Figure 
10, you'll want not only the newly created part of the content region to be 
updated, but also the two rectangular areas containing the (former) size box and 
scroll bars; before calling SizeWindow, you can call InvalRect twice to 
accumulate those areas into the update region. In case the window is made 
smaller, you'll want the new size box and scroll bar areas to be updated, and so 
can similarly call InvalRect for those areas after calling SizeWindow. See 
Figure 12 for an illustration of this type of update region maintenance. 


As another example, Suppose your application scrolls up text in a document 
window and wants to show new text added at the bottom of the window. You can 
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cause the added text to be redrawn by accumulating that area into the update 
region with InvalRect. 


PROCEDURE InvalRgn (badRgn: RgnHandle) ; 


InvalRgn is the same as InvalRect but for a region that has changed rather than 
a rectangle. 
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Figure 12-Update Region Maintenance with InvalRect 


Figure 12—Update Region Maintenance with InvalRect 
PROCEDURE ValidRect (goodRect: Rect); 


ValidRect removes goodRect from the update region of the window whose grafPort 
is the current port. This tells the Window Manager that the application has 
already drawn the rectangle and to cancel any updates accumulated for that area. 
The rectangle is clipped to the window's content region and is given in local 
coordinates. Using ValidRect results in better performance and less redundant 
redrawing in the window. 


For example, suppose you've called SizeWindow with fUpdate=TRUE for a document 
window that contains a size box or scroll bars. Depending on the dimensions of 
the newly sized window, the new size box and scroll bar areas may or may not 
have been accumulated into the window's update region. After calling SizeWindow, 
you can redraw the size box or scroll bars immediately and then call ValidRect 
for the areas they occupy in case they were in fact accumulated into the update 
region; this will avoid redundant drawing. 


PROCEDURE ValidRgn (goodRgn: RgnHandle) ; 
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ValidRgn is the same as ValidRect but for a region that has been drawn rather 
than a rectangle. 


PROCEDURE BeginUpdate (theWindow: WindowPtr); 


Call BeginUpdate when an update event occurs for theWindow. BeginUpdate replaces 
the visRgn of the window's grafPort with the intersection of the visRgn and the 
update region and then sets the window's update region to an empty region. You 
would then usually draw the entire content region, though it suffices to draw 
only the visRgn; in either case, only the parts of the window that require 
updating will actually be drawn on the screen. Every call to BeginUpdate must be 
balanced by a call to EndUpdate. (See "How a Window is Drawn".) 


Note: In Pascal, BeginUpdate and EndUpdate calls can't be nested (that is, 
you must call EndUpdate before the next call to BeginUpdate). 


Assembly-language note: A handle to a copy of the original visRgn (in 
global coordinates) is stored in the global 
variable SaveVisRgn. You can nest BeginUpdate and 
EndUpdate calls in assembly language if you save 
and restore this region. 


PROCEDURE EndUpdate (theWindow: WindowPtr); 


Call EndUpdate to restore the normal visRgn of theWindow's grafPort, which was 
changed by BeginUpdate as described above. 


Color Window Routines 


FUNCTION NewCWindow (wStorage: Ptr; boundsRect: Rect; title: Str255; 
visible: BOOLEAN; procID: INTEGER; behind: WindowPtr; 
goAwayFlag: BOOLEAN; refCon: LONGINT) : WindowPtr; 

[Macintosh IT] 


The NewCWindow routine creates a new color window. This routine is similar to 
the old routine NewWindow, but creates a window based on a cGrafPort instead of 
an old-style grafPort. 


FUNCTION GetNewCWindow (windowID: INTEGER; wStorage: Ptr; 
behind: CWindowPtr) : WindowPtr; [Macintosh ITI] 


The GetNewCWindow routine creates a new color window from a template in a 
resource file. It's analogous to the old routine GetNewwindow, but it creates a 
window based on a cGrafPort instead of an old-style grafPort. GetNewCWindow 
checks the 'wctb' resource, and if it contains the same resource ID, it colors 
the window. The backColor of the window is set to the new content color. This 
allows an application to begin its update with an EraseRect without changing the 
background color. 


PROCEDURE SetWinColor (theWindow: WindowPtr; newColorTable: WCTabHandle) ; 
[Macintosh IT] 
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The SetWinColor routine sets a window's color table. If the window currently 
has no auxiliary window record, a new one is created with the given color table 
and added to the head of the auxiliary window list. If there is already an 
auxiliary record for the window, its color table is replaced by the contents of 
newColorTable. The window is then automatically redrawn in the new colors. If 
SetWinColor is performed on a cWindow, it sets the backColor of the window to 
the new content color. This allows an application to begin its update without 
changing the background color. 


If newColorTable has the same contents as the default color table, the window's 
existing auxiliary record and color table are removed from the auxiliary window 
list and deallocated. If theWindow = NIL, the operation modifies the default 
color table in memory. The system never disposes of color tables that are 
resources when the resource bit is set; 'wctb' resources can't be purgeable. 


FUNCTION GetAuxWin (theWindow: WindowPtr; 
VAR awHndl: AuxWinHandle) : BOOLEAN; [Macintosh ITI] 


The GetAuxWin routine returns a handle to a window's auxiliary window record: 


e If the given window has an auxiliary record, its handle is returned in 
awHndl and the function returns TRUE. 

e If the window has no auxiliary record, a handle to the default record 
is returned in awHndl and the function returns FALSE. 

¢ If theWindow = NIL, a handle to the default record is returned in awHndl 
and the function returns TRUE. 


FUNCTION GetWVariant (whichWindow:WindowPtr): INTEGER; 
[Macintosh Plus, Macintosh SE, Macintosh II] 


GetWVariant returns the variant code for the window described by whichWindow. 
See the section "Defining Your Own Windows" for more information about variants. 


FUNCTION GetGrayRgn : regionHandle; 
[Macintosh Plus, Macintosh SE, Macintosh II] 


The GetGrayRgn function returns a handle to the current desktop region stored in 
the global variable GrayRgn. 


Miscellaneous Routines 

PROCEDURE SetWRefCon (theWindow: WindowPtr; data: LONGINT); 
SetWRefCon sets theWindow's reference value to the given data. 
FUNCTION GetWRefCon (theWindow: WindowPtr) : LONGINT; 
GetWRefCon returns theWindow's current reference value. 


PROCEDURE SetWindowPic (theWindow: WindowPtr; pic: PicHandle); 


@ SpInside Macintosh * Version 1.0 * November 1989 * Apple Computer 
THE WINDOW MANAGER ¢« 45 of 67 


SetWindowPic stores the given picture handle in the window record for theWindow, 
so that when theWindow's contents are to be drawn, the Window Manager will draw 
this picture rather than generate an update event. 


FUNCTION GetWindowPic (theWindow: WindowPtr) : PicHandle; 


GetWindowPic returns the handle to the picture that draws theWindow's contents, 
previously stored with SetWindowPic. 


FUNCTION PinRect (theRect: Rect; thePt: Point) : LONGINT; 


PinRect "pins" thePt inside theRect: If thePt is inside theRect, thePt is 
returned; otherwise, the point associated with the nearest pixel within theRect 
is returned. (The high-order word of the long integer returned is the vertical 
coordinate; the low-order word is the horizontal coordinate.) More precisely, 
for theRect (left,top) (right,bottom) and thePt (h,v), PinRect does the 
following: 


e If h < left, it returns left. 

¢ If v < top , it returns top. 

e If h > right , it returns right—1. 
¢ If v > bottom, it returns bottom—1. 


Note: The 1 is subtracted when thePt is below or to the right of theRect 
so that a pixel drawn at that point will lie within theRect. However, 
if thePt is exactly on the bottom or right edge of theRect, 1 should 
be subtracted but isn't. 


FUNCTION DragGrayRgn (theRgn: RgnHandle; startPt: Point; 
lmitRect, slopRect: Rect; axis: INTEGER; 
actionProc:ProcPtr):LONGINT; [Macintosh II] 


Called when the mouse button is down inside theRgn, DragGrayRgn pulls a dotted 
(gray) outline of the region around, following the movements of the mouse until 
the button is released. DragWindow calls this function before actually moving 
the window. You can call it yourself to pull around the outline of any region, 
and then use the information it returns to determine where to move the region. 


On multiple-screen systems, the Window Manager now checks the screen rectangle 
(screenBits.bounds) when the DragGrayRgn routine is called. This allows the 
object being dragged to be positioned anywhere on the multiscreen desktop. If 
the dragging bounds are based on screenBits.bound, the dragging boundsRect will 
be changed to the bounding box of the grayRgn. The Window Manager's criteria for 
modifying the bounds are (1) the left, bottom, and right are within six pixels 
of screenBits.bound, and (2) the top is within 36 pixels of 
screenBits.bounds.top. If the dragging bounds are modified, the lmitRect 
parameter is also similarly modified. 


Note: DragGrayRgn alters the region; if you don't want the original region 
changed, pass DragGrayRgn a handle to a copy. 


The startPt parameter is assumed to be the point where the mouse button was 
Originally pressed, in the local coordinates of the current grafPort. 
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LmitRect and slopRect are also in the local coordinates of the current grafPort. 
To explain these parameters, the concept of "offset point" must be introduced: 
This is initially the point whose vertical and horizontal offsets from the top 
left corner of the region's enclosing rectangle are the same as those of 
startPt. The offset point follows the mouse location, except that DragGrayRgn 
will never move the offset point outside limitRect; this limits the travel of 
the region's outline (but not the movements of the mouse). SlopRect, which 
should completely enclose limitRect, allows the user some "slop" in moving the 
mouse. DragGrayRgn's behavior while tracking the mouse depends on the location 
of the mouse with respect to these two rectangles: 


e When the mouse is inside lmitRect, the region's outline follows it 
normally. If the mouse button is released there, the region should be 
moved to the mouse location. 

e When the mouse is outside lLmitRect but inside slopRect, DragGrayRgn 
"pins" the offset point to the edge of lmitRect. If the mouse button 
is released there, the region should be moved to this pinned location. 

¢ When the mouse is outside slopRect, the outline disappears from the 
screen, but DragGrayRgn continues to follow the mouse; if it moves back 
into slopRect, the outline reappears. If the mouse button is released 
outside slopRect, the region should not be moved from its original 
position. 


Figure 13 illustrates what happens when the mouse is moved outside lmitRect but 
inside slopRect, for a rectangular region. The offset point is pinned as the 
mouse location moves on. 


If the mouse button is released within slopRect, the high-order word of the 
value returned by DragGrayRgn contains the vertical coordinate of the ending 
mouse location minus that of startPt and the low-order word contains the 
difference between the horizontal coordinates. If the mouse button is released 
outside slopRect, both words contain —32768 ($8000). 
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Figure 13—DragGrayRgn Operation on a Rectangular Region 
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The axis parameter allows you to constrain the region's motion to only one axis. 
It has one of the following values: 


CONST noConstraint = 0; {no constraint} 
hAxisOnly = 1; {horizontal axis only} 
vAxisOnly = 2; {vertical axis only} 


If an axis constraint is in effect, the outline will follow the mouse's 
movements along the specified axis only, ignoring motion along the other axis. 
With or without an axis constraint, the mouse must still be inside the slop 
rectangle for the outline to appear at all. 


The actionProc parameter is a pointer to a procedure that defines some action to 
be performed repeatedly for as long as the user holds down the mouse button; the 
procedure should have no parameters. If actionProc is NIL, DragGrayRgn simply 
retains control until the mouse button is released. 


Assembly-language note: DragGrayRgn calls the procedure pointed to by the 
global variable DragHook, if any, as long as the 
mouse button is held down. (If there's an actionProc 
procedure, the actionProc procedure is called first.) 


If you want the region's outline to be drawn in a 
pattern other than gray, you can store the pattern in 
the global variable DragPattern and then invoke the 
macro DragTheRgn. 


Advanced Routines 
PROCEDURE GetCWMgrPort (VAR wport: CGrafPtr); [Macintosh II] 


The WMgrCPort is a parallel structure to the WMgrPort. The GetCWMgrPort returns 
the address of the WMgrCPort. In Apple-provided 'WDEF' resources, all drawing is 
done in the WMgrCPort to allow full color drawing, rather than just the eight 
QuickDraw colors. 


PROCEDURE SetDeskCPat (deskPixPat: PixPatHandle); [Macintosh II] 


Note: This routine is not for use by applications, and its description is 
only included for informational purposes. 


The SetDeskCPat procedure sets the desktop pattern to a given pixel pattern, 
allowing it to be drawn in more than two colors if desired. The desktop is 
automatically redrawn in the new pattern. If deskPixPat is an old-style binary 
pattern (patType = 0), it will be drawn in the current foreground and background 
colors. If the pixPatHandle is NIL, the standard binary deskPat 

('ppat' resource = 16) will be used. 


The standard desktop painting routines can paint either in the existing binary 
pattern (kept in global variable DeskPat) or in a new pixel pattern. The desk 
pattern used at startup is determined by the value of another bit flag called 
pCDeskPat. If this is pCDeskPat = 0, the new pixel pattern is used; for all 
other values, the binary pattern is used by default. The color pattern can be 
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changed through use of the Control Panel or through the use of SetDeskCPat, but 
only the Control Panel changes the value of pCDeskPat in parameter RAM. 


Low-Level Routines 


These routines are called by higher-level routines; normally you won't need to 
call them yourself. 


FUNCTION CheckUpdate (VAR theEvent: EventRecord) : BOOLEAN; 


CheckUpdate is called by the Toolbox Event Manager. From the front to the back 
in the window list, it looks for a visible window that needs updating (that is, 
whose update region is not empty). If it finds one whose window record contains 
a picture handle, it draws the picture (doing all the necessary region 
manipulation) and looks for the next visible window that needs updating. If it 
ever finds one whose window record doesn't contain a picture handle, it stores 
an update event for that window in theEvent and returns TRUE. If it never finds 
such a window, it returns FALSE. 


PROCEDURE ClipAbove (window: WindowPeek) ; 

ClipAbove sets the clipRgn of the Window Manager port to be the desktop 
intersected with the current clipRgn, minus the structure regions of all the 
windows in front of the given window. 


Assembly-language note: ClipAbove gets the desktop region from the global 
variable GrayRgn. 


PROCEDURE SaveOld (window: WindowPeek) ; 
SaveOld saves the given window's current structure region and content region for 
the DrawNew operation (see below). It must be balanced by a subsequent call to 
DrawNew. 
PROCEDURE DrawNew (window: WindowPeek; update: BOOLEAN) ; 
If the update parameter is TRUE, DrawNew updates the area 
(OldStructure XOR NewStructure) UNION (OldContent XOR NewContent) 
where OldStructure and OldContent are the structure and content regions saved by 
the SaveOld procedure, and NewStructure and NewContent are the current structure 
and content regions. It erases the area and adds it to the window's update 
region. If update is FALSE, it only erases the area. 
Warning: In Pascal, SaveOld and DrawNew are not nestable. 
Assembly-language note: In assembly language, you can nest SaveOld and 
DrawNew if you save and restore the values of the 
global variables OldStructure and OldContent. 


PROCEDURE PaintOne (window: WindowPeek; clobberedRgn:RgnHandle); [Macintosh ITI] 
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PaintOne "paints" the given window, clipped to clobberedRgn and all windows 
above it: It draws the window frame and, if some content is exposed, erases the 
exposed area (paints it with the background pattern) and adds it to the window's 
update region. If the window parameter is NIL, the window is the desktop and so 
is painted with the desktop pattern. 


The PaintOne routine is modified to improve the performance of updates when 
differently colored windows are in use. Formerly, the Window Manager collected 
the update region of multiple windows into a single region, then erased this 
single region to white. In a color environment, different windows may need to be 
erased to different colors, so the previously used monochrome optimization is 
disabled. Each uncovered window is now erased separately, as if the PaintWhite 
global variable was always set to TRUE. Software that uses the PaintWhite and 
SaveUpdate flags may appear slightly different when update events are being 
processed. 


PaintOne tests to see if a window has an old or new grafPort, and sets either 
the wMgrPort or wMgrCPort as appropriate. This allows color windows the full RGB 
range when being erased to their content color. 


Assembly-language note: The global variables SaveUpdate and PaintWhite 
are flags used by PaintOne. Normally both flags are 
set. Clearing SaveUpdate prevents clobberedRgn from 
being added to the window's update region. Clearing 
PaintWhite prevents clobberedRgn from being erased 
before being added to the update region (this is 
useful, for example, if the background of the window 
isn't the background pattern). The Window Manager 
sets both flags periodically, so you should clear 
the appropriate flag just before each situation you 
wish it to apply to. 


PROCEDURE PaintBehind (startWindow: WindowPeek; clobberedRgn: RgnHandle) ; 


PaintBehind calls PaintOne for startWindow and all the windows behind 
startWindow, clipped to clobberedRgn. 


Assembly-language note: PaintBehind clears the global variable PaintWhite 
before calling PaintOne, so clobberedRgn isn't 
erased. (PaintWhite is reset after the call to 
PaintOne. ) 

PROCEDURE CalcVis (window: WindowPeek) ; 


CalcVis calculates the visRgn of the given window by starting with its content 
region and subtracting the structure region of each window in front of it. 


PROCEDURE CalcVisBehind (startWindow: WindowPeek; clobberedRgn: RgnHandle); 


Assembly-language note: The macro you invoke to call CalcVisBehind from 
assembly Language is named CalcVBehind. 


CalcVisBehind calculates the visRgns of startWindow and all windows behind 
startWindow that intersect clobberedRgn. It should be called after PaintBehind. 
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DEFINING YOUR OWN WINDOWS 


Certain types of windows, such as the standard document window, are predefined 
for you. However, you may want to define your own type of window—maybe a round 
or hexagonal window, or even a window shaped like an apple. QuickDraw and the 
Window Manager make it possible for you to do this. 


Note: For the convenience of your application's user, remember to conform 
to the Macintosh User Interface Guidelines for windows as much as 
possible. 


To define your own type of window, you write a window definition function and 
store it in a resource file. When you create a window, you provide a window 
definition ID, which leads to the window definition function. The window 
definition ID is an integer that contains the resource ID of the window 
definition function in its upper 12 bits and a variation code in its lower four 
bits. Thus, for a given resource ID and variation code, the window definition ID 
is 


16 * resource ID + variation code 


The variation code allows a single window definition function to implement 
several related types of window as "variations on a theme". For example, the 
dBoxProc type of window is a variation of the standard document window; both use 
the window definition function whose resource ID is 0, but the document window 
has a variation code of 0 while the dBoxProc window has a variation code of 1. 


The Window Manager calls the Resource Manager to access the window definition 
function with the given resource ID. The Resource Manager reads the window 
definition function into memory and returns a handle to it. The Window Manager 
stores this handle in the windowDefProc field of the window record, along with 
the variation code in the high-order byte of that field. Later, when it needs to 
perform a type-dependent action on the window, it calls the window definition 
function and passes it the variation code as a parameter. Figure 14 illustrates 
this process. 
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Figure 14-Window Definition Handling 


Figure 14—-Window Definition Handling 


The Window Definition Function 


The window definition function is usually written in assembly language, but may 
be written in Pascal. 


Assembly-language note: The function's entry point must be at the beginning. 


You may choose any name you wish for your window definition function. Here's how 
you would declare one named MyWindow: 


FUNCTION MyWindow (varCode: INTEGER; theWindow: WindowPtr; message: INTEGER; 
param: LONGINT) : LONGINT; 


VarCode is the variation code, as described above. 


TheWindow indicates the window that the operation will affect. If the window 
definition function needs to use a WindowPeek type of pointer more than a 
WindowPtr, you can simply specify WindowPeek instead of WindowPtr in the 
function declaration. 


The message parameter identifies the desired operation. It has one of the 
following values: 


CONST wDraw = Q; {draw window frame} 
wHit = 1; {tell what region mouse button was pressed in} 
wCalcRgns = 2; {calculate strucRgn and contRgn} 
wNew = 3; {do any additional window initialization} 
wDispose = 4; {take any additional disposal actions} 
wGrow = 5; {draw window's grow image} 
wDrawGIcon = 6; {draw size box in content region} 
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As described below in the discussions of the routines that perform these 
operations, the value passed for param, the last parameter of the window 
definition function, depends on the operation. Where it's not mentioned below, 
this parameter is ignored. Similarly, the window definition function is expected 
to return a function result only where indicated; in other cases, the function 
should return 0. 


Note: "Routine" here doesn't necessarily mean a procedure or function. 
While it's a good idea to set these up as subprograms inside the 
window definition function, you're not required to do so. 


The Draw Window Frame Routine 


When the window definition function receives a wDraw message, it should draw the 
window frame in the current grafPort, which will be the Window Manager port. 
(For details on drawing, see the QuickDraw chapter. ) 


This routine should make certain checks to determine exactly what it should do. 
If the visible field in the window record is FALSE, the routine should do 
nothing; otherwise, it should examine the value of param received by the window 
definition function, as described below. 


If param is 0, the routine should draw the entire window frame. If the hilited 
field in the window record is TRUE, the window frame should be highlighted in 
whatever way is appropriate to show that this is the active window. If 
goAwayFlag in the window record is also TRUE, the highlighted window frame 
should include a go-away region; this is useful when you want to define a window 
such that a particular window of that type may or may not have a go-away region, 
depending on the situation. 


Special action should be taken if the value of param is wInGoAway (a predefined 
constant, equal to 4, which is one of those returned by the hit routine 
described below). If param is wInGoAway, the routine should do nothing but 
"toggle" the state of the window's go-away region from unhighlighted to 
highlighted or vice versa. The highlighting should be whatever is appropriate to 
show that the mouse button has been pressed inside the region. Simple inverse 
highlighting may be used or, as in document windows, the appearance of the 
region may change considerably. In the latter case, the routine could use a 
"mask" consisting of the unhighlighted state of the region XORed with its 
highlighted state (where XOR stands for the logical operation "exclusive or"). 
When such a mask is itself XORed with either state of the region, the result is 
the other state; Figure 15 illustrates this for a document window. 
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Figure 15—Toggling the Go-Away Region 
Typically the window frame will include the window's title, which should be in 
the system font and system font size. The Window Manager port will already be 
set to use the system font and system font size. 


Note: Nothing drawn outside the window's structure region will be visible. 


The Hit Routine 


When the window definition function receives a wHit message, it also receives as 
its param value the point where the mouse button was pressed. This point is 
given in global coordinates, with the vertical coordinate in the high-order word 
of the long integer and the horizontal coordinate in the low-order word. The 
window definition function should determine where the mouse button "hit" and 
then return one of these predefined constants: 


CONST wNoHit = 0; {none of the following} 
wInContent = 1; {in content region (except grow, if active)} 
wInDrag = 2; {in drag region} 
wInGrow = 3; {in grow region (active window only) } 
wInGoAway = 4; {in go-away region (active window only) } 


Usually, wNoHit means the given point isn't anywhere within the window, but this 
is not necessarily so. For example, the document window's hit routine returns 
wNoHit if the point is in the window frame but not in the title bar. 


@ SpInside Macintosh * Version 1.0 * November 1989 * Apple Computer 
THE WINDOW MANAGER ¢« 54 of 67 


The constants wInGrow and wInGoAway should be returned only if the window is 
active, since by convention the size box and go-away region won't be drawn if 
the window is inactive (or, if drawn, won't be operable). In an inactive 
document window, if the mouse button is pressed in the title bar where the close 
box would be if the window were active, the hit routine returns winDrag. 


Of the regions that may have been hit, only the content region necessarily has 
the structure of a region and is included in the window record. The hit routine 
can determine in any way it likes whether the drag, grow, or go-away "region" 
has been hit. 


The Routine to Calculate Regions 


The routine executed in response to a wCalcRgns message should calculate the 
window's structure region and content region based on the current grafPort's 
portRect. These regions, whose handles are in the strucRgn and contRgn fields, 
are in global coordinates. The Window Manager will request this operation only 
if the window is visible. 


Warning: When you calculate regions for your own type of window, do not 
alter the clipRgn or the visRgn of the window's grafPort. The 
Window Manager and QuickDraw take care of this for you. Altering 
the clipRgn or visRgn may result in damage to other windows. 


The Initialize Routine 


After initializing fields as appropriate when creating a new window, the Window 
Manager sends the message wNew to the window definition function. This gives the 
definition function a chance to perform any type-specific initialization it may 
require. For example, if the content region is unusually shaped, the initialize 
routine might allocate space for the region and store the region handle in the 
dataHandle field of the window record. The initialize routine for a standard 
document window does nothing. 


The Dispose Routine 


The Window Manager's CloseWindow and DisposeWindow procedures send the message 
wDispose to the window definition function, telling it to carry out any 
additional actions required when disposing of the window. The dispose routine 
might, for example, release space that was allocated by the initialize routine. 
The dispose routine for a standard document window does nothing. 


The Grow Routine 


When the window definition function receives a wGrow message, it also receives a 
pointer to a rectangle as its param value. The rectangle is in global 
coordinates and is usually aligned at its top left corner with the portRect of 
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the window's grafPort. The grow routine should draw a grow image of the window 
to fit the given rectangle (that is, whatever is appropriate to show that the 
window's size will change, such as an outline of the content region). The Window 
Manager requests this operation repeatedly as the user drags inside the grow 
region. The grow routine should draw in the current grafPort, which will be the 
Window Manager port, and should use the grafPort's current pen pattern and pen 
mode, which are set up (as gray and notPatXor) to conform to the Macintosh User 
Interface Guidelines. 


The grow routine for a standard document window draws a dotted (gray) outline of 
the window and also the lines delimiting the title bar, size box, and scroll bar 
areas. 


The Draw Size Box Routine 


If the window's grow region is in the content region, the wDrawGIcon message 
tells the window definition function to draw the size box in the grow region if 
the window is active (highlighted); if the window is inactive it should draw 
whatever is appropriate to show that the window temporarily can't be sized. For 
active document windows, this routine draws the size box icon in the bottom 
right corner of the portRect of the window's grafPort, along with the lines 
delimiting the size box and scroll bar areas; for inactive windows, it draws 
just the delimiting lines, and erases the size box icon. 


If the grow region is located in the window frame rather than the content 
region, this routine should do nothing. 


The Color Definition Procedure 


Like standard windows, custom window structures can be drawn in full color. On 
the Macintosh II, a new data structure known as the WMgrCPort, which opens a 
cGrafPort, is introduced. This data structure is analogous to the existing 
WMgrPort, and defines the desktop area of the Window Manager, allowing desktop 
objects (such as window frames) to be drawn in full color. The standard defprocs 
included in the Macintosh II ROM and on the system disk, are universal 
defprocs—that is, they support the full color capabilities of the Macintosh II 
while maintaining full compatibility on noncolor Macintoshes. Since applications 
can be transported between color and noncolor Macintoshes on disk, custom 
defprocs associated with applications should be written in this same universal 
style. 


To write a universal defproc, the defproc should, upon entry, identify the 
capabilities of the machine on which it is running by using the SysEnvirons 
call. If the machine doesn't support color, then all previous rules for writing 
defprocs should be followed. 


If the machine is equipped with Color QuickDraw, then a number of extra steps 
should be performed: 


¢ First, the defproc should change the current port from the WMgrPort to 
the WMgrCPort, to allow the system to draw in the full range of RGBColors. 
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e Next, the defproc should update certain fields in the WMgrCPort to the 
values of the corresponding fields in the WMgrPort. The fields that 
should be updated are the pen attributes, the text attributes, and bkPat. 
The vis and clip regions are automatically transferred by the Window 
Manager. 


Note: The parallelism of the WMgrPort and the WMgrCPort is maintained only 
by the defprocs. All defprocs that draw in the WMgrPort should follow 
these rules even if the changed fields don't affect their operation. 


When the two ports are in parallel, the color defproc can proceed with its 
drawing. Note that the GetAuxWin routine, described above, can be used to get 
the intended colors for the window parts from the AuxWinList. As with all color 
objects, highlighting shouldn't be performed by inverting; the forecolor and 
backcolor should be reversed and the highlighted item redrawn. No special steps 
need be taken on exit from the defproc. All other features and requirements of 
defprocs are unchanged. 


Note: For compatibility with systems using MultiFinder™, no drawing should 
take place in either the WMgrPort or the WMgrCPort unless the drawing 
occurs within a definition procedure. 
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FORMATS OF RESOURCES FOR WINDOWS 


The Window Manager function GetNewWindow takes the resource ID of a window 
template as a parameter, and gets from the template the same information that 
the NewWindow function gets from six of its parameters. The resource type for a 
window template is 'WIND', and the resource data has the following format: 


Number of bytes Contents 
8 bytes Same as boundsRect parameter to NewWindow 
2 bytes Same as procID parameter to NewWindow 
2 bytes Same as visible parameter to NewWindow 
2 bytes Same as goAwayFlag parameter to NewWindow 
4 bytes Same as refCon parameter to NewWindow 
n bytes Same as title parameter to NewWindow 


(1-byte length in bytes, followed by the 
characters of the title) 


The resource type for a window definition function is 'WDEF', and the resource 
data is simply the compiled or assembled code of the function. 
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SUMMARY OF THE WINDOW MANAGER 


Constants 
CONST 


{ Window definition IDs } 


documentProc = 0; {standard document window} 
dBoxProc = i) {alert box or modal dialog box} 
plainDBox = 2; {plain box} 

altDBoxProc = 3; {plain box with shadow} 
noGrowDocProc = 4; {document window without size box} 
rDocProc = 16; {rounded-corner window} 


{ Window class, in windowKind field of window record } 


dialogKind 
userKind 


2; {dialog or alert window} 
8; {window created directly by the application} 


{ Values returned by FindWindow } 


inDesk = 0; {none of the following} 

inMenuBar = 13; {in menu bar} 

inSysWindow = 2; {in system window} 

inContent = 3; {in content region (except grow, if active) } 
inDrag = 4; {in drag region} 

inGrow = 5; {in grow region (active window only) } 
inGoAway = 6; {in go-away region (active window only) } 
inZoomIn = 7; {in zoom box for zooming in} 

inZoom0ut = 8; {in zoom box for zooming out} 


{ Axis constraints for DragGrayRgn } 


noConstraint = 0; {no constraint} 
hAxisOnly = 1; {horizontal axis only} 
vAxisOnly = 2; {vertical axis only} 


{ Messages to window definition function } 


wDraw = 0; {draw window frame} 

wHit = 1; {tell what region mouse button was pressed in} 
wCalcRgns = 2; {calculate strucRgn and contRgn} 

wNew = 3; {do any additional window initialization} 
wDispose = 4; {take any additional disposal actions} 

wGrow = 5" {draw window's grow image} 

wDrawGIcon = 6; {draw size box in content region} 


{ Values returned by window definition function's hit routine } 


wNoHit = 0; {none of the following} 
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wiInContent = 1; {in content region (except grow, if active)} 
wInDrag = 2; {in drag region} 

wInGrow = 3; {in grow region (active window only) } 
wInGoAway = 4; {in go-away region (active window only) } 
wInZoomIn = 5; {in zoom box for zooming in} 

wInZoomOut = 6; {in zoom box for zooming out} 


{ Resource ID of desktop pattern } 


deskPatID 16; 


{ Window Part Identifiers which correlate color table entries } 


{ with window elements } 
wContentColor = 0; 
wFrameColor = 1; 
wTextColor = 23 
wHiliteColor = 3; 
wlitleBarColor = 4; 
Data Types 
TYPE 
WindowPtr = GrafPtr; 
WindowPeek = “WindowRecord; 
WindowRecord = RECORD 
port: GrafPort; {window's grafPort} 
windowKind: INTEGER; {window class} 
visible: BOOLEAN; {TRUE if visible} 
hilited: BOOLEAN; {TRUE if highlighted} 
goAwayFlag: BOOLEAN; {TRUE if has go-away region} 
spareF lag: BOOLEAN; {reserved for future use} 
strucRgn: RgnHandle; {structure region} 
contRgn: RgnHandle; {content region} 
updateRgn: RgnHandle; {update region} 
windowDefProc: Handle; {window definition function} 
dataHandle: Handle; {data used by windowDefProc} 
titleHandle: StringHandle; {window's title} 
titleWidth: INTEGER; {width of title in pixels} 
controlList: ControlHandle; {window's control list} 
nextWindow: WindowPeek; {next window in window List} 
windowPic: PicHandle; {picture for drawing window} 
refCon: LONGINT {window's reference value} 
END; 
wStateData = RECORD; 
userState: Rect; 
stdState: Rect 
END; 
CWindowPtr = CGrafPtr; 
CWindowPeek = “CWindowRecord; 
CWindowRecord = RECORD {all fields remain the same as before} 
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port: CGrafPort; {window's CGrafPort} 
windowKind: INTEGER; {window class} 
visible: BOOLEAN; {TRUE if visible} 
hilited: BOOLEAN; {TRUE if highlighted} 
goAwayFlag: BOOLEAN; {TRUE if has go-away region} 
SpareFlag: BOOLEAN; {reserved for future use} 
strucRgn: RgnHandle; {structure region} 
contRgn: RgnHandle; {content region} 
updateRgn: RgnHandle; {update region} 
windowDefProc: Handle; {window definition function} 
dataHandle: Handle; {data used by windowDefProc} 
titleHandle: StringHandle; {window's title} 
titleWidth: INTEGER; {width of title in pixels} 
controlList: ControlHandle; {window's control list} 
nextWindow: CWindowPeek; {next window in window List} 
windowPic: PicHandle; {picture for drawing window} 
refCon: LONGINT {window's reference value} 
END; 
AuxWinHandle = “*AuxWinPtr; 
AuxWinPtr = “AuxWinRec; 
AuxWinRec = RECORD 
awNext: AuxWinHandle; {handle to next record in list} 
awOwner: WindowPtr; {pointer to owning window} 
awCTable: CTabHandle; {handle to window's color table} 
dialogCItem: Handle; {private storage for } 
{ Dialog Manager} 
awF lags: LONGINT; {reserved for future use} 
awReserved: CTabHandle; {reserved for future use} 
awRefCon: LONGINT {reserved for } 
{ application use} 
END; 
WCTabHandle = “WCTabPtr; 
WCTabPtr = “WinCTab; 
WinCTab = RECORD 
wCSeed: LONGINT; {unique identifier from table} 
wCReserved: INTEGER; {not used for windows} 
ctSize: INTEGER; {number of entries in table —1} 
ctTable: Array [0..4] of ColorSpec; {array of } 
{ ColorSpec records} 
END; 
Routines 
Initialization and Allocation 
PROCEDURE InitWindows; 
PROCEDURE GetWMgrPort (VAR wPort: GrafPtr); 
FUNCTION NewWindow (wStorage: Ptr; boundsRect: Rect; title: Str255; 
visible: BOOLEAN; procID: INTEGER; 


behind: WindowPtr; goAwayFlag: 
refCon: LONGINT) WindowPtr; 


BOOLEAN; 
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FUNCTION GetNewWindow (windowID: INTEGER; wStorage: Ptr; 
behind: WindowPtr) : WindowPtr; 

PROCEDURE CloseWindow (theWindow: WindowPtr); 

PROCEDURE DisposeWindow (theWindow: WindowPtr) ; 


Window Display 


PROCEDURE SetWTitle 
PROCEDURE GetWTitle 


(theWindow: WindowPtr; title: Str255); 
(theWindow: WindowPtr; VAR title: Str255); 
PROCEDURE SelectWindow (theWindow: WindowPtr); 

PROCEDURE HideWindow (theWindow: WindowPtr); 

PROCEDURE ShowWindow (theWindow: WindowPtr); 

PROCEDURE ShowHide (theWindow: WindowPtr; showFlag: BOOLEAN) ; 
PROCEDURE HiliteWindow (theWindow: WindowPtr; fHilite: BOOLEAN); 
PROCEDURE BringToFront (theWindow: WindowPtr); 

PROCEDURE SendBehind (theWindow, behindWindow: WindowPtr); 
FUNCTION FrontWindow : WindowPtr; 

PROCEDURE DrawGrowIcon (theWindow: WindowPtr); 


Mouse Location 


FUNCTION FindWindow (thePt: Point; VAR whichWindow: WindowPtr) : INTEGER; 
FUNCTION TrackGoAway (theWindow: WindowPtr; thePt: Point) : BOOLEAN; 


Window Movement and Sizing 


PROCEDURE MoveWindow (theWindow: WindowPtr; hGlobal,vGlobal: INTEGER; 
front: BOOLEAN); 
PROCEDURE DragWindow (theWindow: WindowPtr; startPt: Point; 
boundsRect: Rect); 
FUNCTION GrowWindow (theWindow: WindowPtr; startPt: Point; 
sizeRect: Rect) : LONGINT; 
PROCEDURE SizeWindow (theWindow: WindowPtr; w,h: INTEGER; fUpdate: BOOLEAN); 
FUNCTION TrackBox (theWindow: WindowPtr; thePt: Point; 
partCode: INTEGER) : BOOLEAN; 
PROCEDURE ZoomWindow (theWindow: WindowPtr; partCode: INTEGER; 
front: BOOLEAN); 


Update Region Maintenance 


PROCEDURE InvalRect (badRect: Rect); 
PROCEDURE InvalRgn (badRgn: RgnHandle); 
PROCEDURE ValidRect (goodRect: Rect); 
PROCEDURE ValidRgn (goodRgn: RgnHandle) ; 
PROCEDURE BeginUpdate (theWindow: WindowPtr); 
PROCEDURE EndUpdate (theWindow: WindowPtr); 


Color Window Routines 


FUNCTION NewCWindow (wStorage: Ptr; boundsRect: Rect; title: Str255; 
visible: BOOLEAN; procID: INTEGER; behind: WindowPtr; 
goAwayFlag: BOOLEAN; refCon: LONGINT) : WindowPtr; 

FUNCTION GetNewCWindow (windowID: INTEGER; wStorage: Ptr; 
behind: CWindowPtr) : WindowPtr; 

PROCEDURE SetWinColor (theWindow: WindowPtr; newColorTable: WCTabHandle) ; 
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FUNCTION GetAuxWin 


(theWindow: WindowPtr; 


VAR awHndl: AuxWinHandle) : BOOLEAN; 
FUNCTION GetWVariant (whichWindow:WindowPtr): INTEGER; 
FUNCTION GetGrayRgn regionHandle; [Not in ROM] 
Miscellaneous Routines 
PROCEDURE SetWRefCon (theWindow: WindowPtr; data: LONGINT); 
FUNCTION GetWRefCon (theWindow: WindowPtr) LONGINT; 
PROCEDURE SetWindowPic (theWindow: WindowPtr; pic: PicHandle); 
FUNCTION GetWindowPic (theWindow: WindowPtr) PicHandle; 
FUNCTION PinRect (theRect: Rect; thePt: Point) LONGINT; 
FUNCTION DragGrayRgn (theRgn: RgnHandle; startPt: Point; 
lmitRect, slopRect: Rect; axis: INTEGER; 
actionProc: ProcPtr) LONGINT; 
Advanced Routines 
PROCEDURE GetCWMgrPort (VAR wport: CGrafPtr); 
PROCEDURE SetDeskCPat (deskPixPat: PixPatHandle) ; 
Low-Level Routines 
FUNCTION CheckUpdate (VAR theEvent: EventRecord) BOOLEAN; 
PROCEDURE ClipAbove (window: WindowPeek) ; 
PROCEDURE SaveOld (window: WindowPeek) ; 
PROCEDURE DrawNew (window: WindowPeek; update: BOOLEAN); 
PROCEDURE PaintOne (window: WindowPeek; clobberedRgn: RgnHandle) ; 
PROCEDURE PaintBehind (startWindow: WindowPeek; clobberedRgn: RgnHandle) ; 
PROCEDURE CalcVis (window: WindowPeek) ; 
PROCEDURE CalcVisBehind (startWindow: WindowPeek; clobberedRgn: RgnHandle); 
Diameters of Curvature for Rounded-Corner Windows 
Window definition ID Diameters of curvature 
rDocProc 16, 16 
rDocProc + 1 4, 4 
rDocProc + 2 6, 6 
rDocProc + 3 8, 8 
rDocProc + 4 10, 10 
rDocProc + 5 12, 12 
rDocProc + 6 20, 20 
rDocProc + 7 24, 24 
Window Definition Function 
FUNCTION MyWindow (varCode: INTEGER; theWindow: WindowPtr; 
message: INTEGER; param: LONGINT) LONGINT; 
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Variables 


GrayRgn {Contains information on size and shape of the current desktop} 
AuxWinHead {Contains handle to the head of the auxiliary window list} 


Assembly-Language Information 
Constants 


; Window definition IDs 


documentProc . EQU 0 sstandard document window 
dBoxProc . EQU 1 ;alert box or modal dialog box 
plainDBox .EQU 2 ;plain box 

altDBoxProc .EQU 3 ;plain box with shadow 
noGrowDocProc  .EQU 4 sdocument window without size box 
rDocProc . EQU 16 srounded-corner window 


; Window class, in windowKind field of window record 


dialogKind .EQU 2 ;dialog or alert window 
userKind . EQU 8 ;window created directly by the application 


; Values returned by FindWindow 


inDesk . EQU 0 ;none of the following 

inMenuBar . EQU 1 ;in menu bar 

inSysWindow .EQU 2 ;in system window 

inContent . EQU 3 ;in content region (except grow, if active) 
inDrag .EQU 4 ;in drag region 

inGrow . EQU 5 ;in grow region (active window only) 
inGoAway .EQU 6 ;in go-away region (active window only) 
inZoomIn . EQU 7 ;in zoom box for zooming in 

inZoomOut . EQU 8 ;in zoom box for zooming out 


; Axis constraints for DragGrayRgn 


noConstraint .EQU 0 ;no constraint 
hAxisOnly .EQU 1 ;horizontal axis only 
vAxisOnly .EQU 2 ;vertical axis only 


; Messages to window definition function 


wD rawMsg .EQU 0 ;draw window frame 

wHitMsg .EQU 1 ;tell what region mouse button was pressed in 
wCalcRgnMsg .EQU 2 ;calculate strucRgn and contRgn 

wInitMsg .EQU 3 ;do any additional window initialization 
wDisposeMsg . EQU 4 ;take any additional disposal actions 
wGrowMsg . EQU 5 ;draw window's grow image 

wGIconMsg .EQU 6 ;draw size box in content region 


; Value returned by window definition function's hit routine 
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wNoHit 
wiInContent 
wInDrag 
winGrow 
wInGoAway 
wiInZoomiIn 
wInZoomOut 


.EQU 0 ;none of the following 

.EQU 1 ;in content region (except grow, if active) 
.EQU 2 ;in drag region 

.EQU 3 ;in grow region (active window only) 

.EQU 4 ;in go-away region (active window only) 
.EQU 5 ;in zoom box for zooming in 

.EQU 6 ;in zoom box for zooming out 


; Resource ID of desktop pattern 


deskPatID 


. EQU 16 


; Window Part Identifiers that correlate color table entries with 
; window elements 


wContentColor EQU 0 

wFrameColor EQU 1 

wlextColor EQU 2 

wHiliteColor EQU 3 

wlitleBarColor EQU 4 

; auxWinRec structure 

nextAuxWin EQU $0 snext in chain [Handle] 

auxWinOwner EQU $4 sowner ID [WindowPtr] 

awCTable EQU $8 ;color table [CTabHandle] 

dialogCItem EQU $C ;handle to dialog manager structures [handle] 
awF lags EQU $10 ;handle for QuickDraw [handle] 

awResrv EQU $14 ;for expansion [longint] 

awRe fCon EQU $18 ;user constant [longint] 

; Global variables 

AuxWinHead EQU $0CDO ; [handle] Window Aux List head 

GrayRgn EQU $9EE ;contains information on size and shape 


; of the current desktop 


Window Record Data Structure 


windowPort 
windowKind 
wVisible 
wHilited 
wGoAway 
wZoom 
structRgn 
contRgn 
updateRgn 
windowDef 
wDataHandle 
wlitleHandle 
wlitleWidth 
wControlList 
nextWindow 
windowPic 


Window's grafPort (portRec bytes) 

Window class (word) 

Nonzero if window is visible (byte) 

Nonzero if window is highlighted (byte) 
Nonzero if window has go-away region (byte) 
Nonzero if window has a zoom-window box (byte) 
Handle to structure region of window 

Handle to content region of window 

Handle to update region of window 

Handle to window definition function 

Handle to standard and user window states 
Handle to window's title (preceded by length) 
Width of title in pixels (word) 

Handle to window's control list 

Pointer to next window in window list 

Picture handle for drawing window 
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wRefCon 
windowSize 


Window's reference value (long) 
Size in bytes of window record 


Window State Data Structure 


userState 
stdState 


Window's user state (rectangle; 8 bytes) 
Window's standard state (rectangle; 8 bytes) 


Special Macro Names 


Pascal name 


CalcVisBehind 
DisposeWindow 
DragGrayRgn 


Variables 


WindowList 
SaveUpdate 
PaintWhite 
CurActivate 
CurDeactive 
GrayRgn 
DeskPattern 
DeskHook 


WMgrPort 
GhostWindow 
DragHook 


DragPattern 
OldStructure 
OldContent 
SaveVisRgn 


Macro name 


_CalcVBehind 
DisposWindow 


_DragGrayRgn or, after setting the global variable 


DragPattern, DragTheRgn 


Pointer to first window in window list 
Flag for whether to generate update events (word) 
Flag for whether to paint window white before update event (word) 
Pointer to window to receive activate event 

Pointer to window to receive deactivate event 


Handle to region drawn as desktop 


Pattern with which desktop is painted (8 bytes) 
Address of procedure for painting desktop or 


responding to clicks on desktop 
Pointer to Window Manager port 


Pointer to window never to be considered frontmost 
Address of procedure to execute during TrackGoAway, 
DragWindow, GrowWindow, and DragGrayRgn 
Pattern of dragged region's outline (8 bytes) 


Handle to saved structure region 
Handle to saved content region 
Handle to saved visRgn 
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Further Reference: 


QuickDraw 

Color QuickDraw 

Toolbox Event Manager 

Resource Manager 

Technical Note #53, MoreMasters Revisited 
Technical Note #79, ZoomWindow 

Technical Note #110, MPW: Writing Standalone Code 
Technical Note #117, Compatibility: Why & How 
Technical Note #194, WMgrPortability 

Technical Note #212, The Joy Of Being 32-Bit Clean 


END OF DOCUMENT 
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